Testare, distribuire e integrare gli agenti

I test, la distribuzione e gli agenti di pubblicazione sono passaggi critici per passare dallo sviluppo all'ambiente di produzione. Microsoft Foundry offre funzionalità complete per la convalida del comportamento dell'agente, la distribuzione nel progetto Foundry e la pubblicazione di agenti come endpoint chiamabili che possono essere usati da consumer e applicazioni esterni.

Strategie di test per gli agenti

Test approfonditi garantisce che gli agenti si comportino in modo affidabile in diversi scenari prima di raggiungere gli utenti. Sia il portale Foundry che l'estensione Visual Studio Code forniscono sandbox per il testing interattivo.

Usando il playground in modo efficace:

• Test del percorso positivo : verificare che l'agente gestisca correttamente le richieste comuni e previste.
• Test dei casi limite - provare input ambigui, informazioni incomplete e richieste insolite per rivelare il modo in cui gli agenti gestiscono l'incertezza.
• Test dei limiti: verificare che l'agente rispetti i limiti definiti nelle istruzioni eseguendo il test delle richieste fuori ambito.
• Test di conversazione a più turni : verificare che l'agente mantenga il contesto tra più scambi e si basa sulle risposte precedenti.
• Test di chiamata dello strumento : verificare che gli agenti chiamino gli strumenti giusti al momento giusto e incorporare correttamente i risultati.

Registrare i risultati dei test per tenere traccia dei miglioramenti e rilevare le regressioni.

Distribuzione di agenti nel progetto

Microsoft Foundry supporta la distribuzione di agenti dal portale o da Visual Studio Code. La distribuzione salva la configurazione dell'agente nel progetto Foundry in modo da poter testare ed eseguire l'iterazione.

Distribuzione dal portale Foundry

1. Vai al tuo agente nel portale Foundry
2. Verificare che i risultati della configurazione e dei test siano soddisfacenti
3. Selezionare Salva dalla pagina dell'agente
4. Confermare le impostazioni di versione e distribuzione

Distribuzione da Visual Studio Code

1. Apri il tuo agente in AI Toolkit
2. Selezionare Salva in Foundry per eseguire il push delle modifiche alla configurazione
3. Per gli agenti ospitati, aprire il menu +Compila negli strumenti di sviluppo e selezionare Distribuisci in Microsoft Foundry
4. Selezionare la configurazione del contenitore e confermare

Entrambi gli approcci mantengono l'agente all'interno dell'area di lavoro del progetto in cui i membri del team possono accedervi e testarlo.

Pubblicazione di agenti su un endpoint

La pubblicazione sposta un agente dall'area di lavoro del progetto in una risorsa di Azure gestita denominata applicazione agente. Questo passaggio rende l'agente chiamabile esternamente tramite un endpoint stabile.

Cosa produce la pubblicazione

Quando si pubblica una versione dell'agente, Foundry crea:

• Applicazione agente : una risorsa di Azure con il proprio URL di chiamata, i criteri di autenticazione e l'identità dell'agente Entra.
• Distribuzione : istanza in esecuzione di una versione specifica dell'agente all'interno dell'applicazione, con gestione del ciclo di vita di avvio/arresto.

La differenza principale tra la distribuzione e la pubblicazione è l'ambito. L'implementazione mantiene l'agente all'interno del progetto. La pubblicazione crea un endpoint dedicato che i consumer esterni possono chiamare senza dover accedere al progetto Foundry.

Pubblicazione dal portale foundry

1. Nel portale selezionare la versione dell'agente da pubblicare
2. Selezionare Pubblica per creare l'applicazione e la distribuzione dell'agente

Pubblicazione da Visual Studio Code

1. Aprire la Palette comandi (CTRL+MAIUSC+P) ed eseguire Microsoft Foundry: Distribuire l'agente ospitato per gli agenti ospitati.
2. Selezionare l'area di lavoro di destinazione e la configurazione del contenitore
3. Confermare e implementare

Dopo la pubblicazione, l'agente viene visualizzato nella sezione Agenti ospitati (anteprima) della visualizzazione albero dell'estensione di AI Toolkit.

L'endpoint dell'applicazione agente

Gli agenti pubblicati espongono un endpoint stabile usando il protocollo API Responses:

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses

Questo URL rimane invariato anche quando si esegue l'implementazione di nuove versioni dell'agente, quindi i consumer downstream non vengono interrotti dagli aggiornamenti.

Autenticazione e identità

Le applicazioni agent usano Microsoft Entra ID per l'autenticazione. I chiamanti devono avere il ruolo Utente di Azure AI sulla risorsa dell'applicazione dell'agente. L'autenticazione con chiave API non è supportata per le applicazioni dell'agente.

Verifica dell'endpoint

Dopo la pubblicazione, verificare che l'endpoint funzioni:

1. Ottenere un token di accesso:

   az account get-access-token --resource https://ai.azure.com
   

2. Chiamare l'endpoint dell'applicazione agente:

   curl -X POST \
     "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
     -H "Authorization: Bearer <access-token>" \
     -H "Content-Type: application/json" \
     -d '{"input":"Say hello"}'
   

Se si riceve 403 Forbidden, verificare che il chiamante abbia il ruolo Utente di Azure AI sulla risorsa dell'applicazione Agente.

Aggiornamento degli agenti pubblicati

Per implementare una nuova versione dell'agente:

1. Apportare modifiche nell'ambiente di sviluppo e testare attentamente
2. Nel portale di Foundry selezionare Pubblica aggiornamenti dal playground dell'agente
3. L'applicazione dell'agente instrada automaticamente il 100% del traffico alla nuova versione

L'URL dell'endpoint rimane invariato, quindi le integrazioni esistenti continuano a funzionare.

Generazione di codice di integrazione

L'estensione Microsoft Foundry VS Code genera codice di integrazione di esempio per connettere l'applicazione a un agente pubblicato:

1. Selezionare l'agente distribuito nella visualizzazione Risorse personali
2. Selezionare Visualizza codice
3. Scegliere la cartella
4. L'estensione genera codice per l'autenticazione, la connessione, l'invio di messaggi e l'elaborazione delle risposte

Modelli di integrazione

I modelli comuni per l'integrazione degli agenti pubblicati includono:

• Applicazioni Web : inviare messaggi utente all'endpoint dell'API Risposte e visualizzare le risposte nell'interfaccia utente. Archiviare la cronologia delle conversazioni sul lato client per le interazioni a più turni.
• Flussi di lavoro basati sulle API : chiamare l'endpoint agente dai servizi back-end attivati da eventi o pianificazioni. Elaborare le risposte a livello di codice per eseguire azioni downstream.
• Interfacce chatbot - Mappare le sessioni utente con le conversazioni. Gestire lo scambio di messaggi in tempo reale tramite l'endpoint.
• Automazione in background : consente di pianificare le chiamate dell'agente per le attività ricorrenti. Inserire i dati di sistema in agenti ed elaborare output per aggiornare i sistemi aziendali.

Considerazioni sulla produzione

La gestione di agenti nell'ambiente di produzione richiede attenzione a diverse aree operative chiave.

• Monitoraggio : tenere traccia dei tempi di risposta, delle chiamate agli strumenti, dei modelli di errore e del consumo di token usando l'integrazione di Application Insights.
• Sicurezza : usare le identità gestite per l'autenticazione, applicare l'accesso con privilegi minimi e definire i criteri di conservazione dei dati.
• Gestione dei costi : monitorare l'utilizzo dei token, impostare i limiti di lunghezza della risposta e implementare la limitazione della velocità per evitare picchi imprevisti.
• Gestione degli errori : implementare la logica di ripetizione dei tentativi con backoff esponenziale per gli errori temporanei. Gestire la limitazione della frequenza con strategie di backoff. Convalidare gli input prima dell'invio agli agenti.
• Gestione delle conversazioni : gli endpoint dell'applicazione agent supportano attualmente solo l'API Risposte senza stato. Archiviare la cronologia delle conversazioni nel client per esperienze a più turni.