Testare, distribuire e integrare gli agenti

  • 9 minuti

Tip

Per altri dettagli, vedi la scheda Testo e immagini .

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 nel Foundry 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. Scegli un metodo di distribuzione:
    • Codice (ZIP Code Deploy) - crea un pacchetto del codice sorgente e distribuisce direttamente senza un'immagine container
    • Contenitore (BYOI) - Distribuire usando un'immagine del contenitore predefinita da Registro Azure Container
  5. Selezionare il modello 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

Quando si crea un agente in Microsoft Foundry, riceve automaticamente un endpoint stabile, la propria identità agente Entra e un blueprint dell'agente. La pubblicazione fa quindi riferimento alla distribuzione dell'agente in modo che i consumer e le applicazioni esterni, inclusi Microsoft Teams e Microsoft 365 Copilot, possano chiamarlo.

Elementi inclusi in ogni agente

Viene effettuato il provisioning di ogni agente creato in Foundry con:

  • Endpoint stabile : URL di chiamata pronto per la produzione che rimane costante anche quando si aggiornano le versioni dell'agente.
  • Identità agente Entra: un'identità Microsoft Entra dedicata con il proprio ambito di controllo degli accessi in base al ruolo, separata dall'identità condivisa del progetto.
  • Criterio di autenticazione - autenticazione Microsoft Entra ID predefinita. I chiamanti devono avere il ruolo Utente Foundry nella risorsa dell'agente. L'autenticazione con chiave API non è supportata.

Importante

Ogni agente riceve la propria identità Entra dedicata. Le autorizzazioni non vengono trasferite automaticamente dall'identità del progetto. È necessario assegnare i ruoli RBAC all'identità dell'agente per tutte le risorse a cui accede l'agente. Se si ignora questo passaggio, le chiamate degli strumenti che funzionano durante lo sviluppo hanno esito negativo con errori di autorizzazione dopo la pubblicazione dell'agente.

Pubblicare in Microsoft Teams e Microsoft 365 Copilot

Dal portale di Foundry è possibile pubblicare agenti in Microsoft Teams e Microsoft 365 Copilot con un unico passaggio, senza dover ricompilare. L'agente passa attraverso una pipeline unificata nelle applicazioni in cui gli utenti lavorano già.

Endpoint dell'agente

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

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/agents/<agent-name>/endpoint/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.

Verifica dell'endpoint

Dopo aver creato e configurato l'agente, 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'agente:

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

Se si riceve 403 Forbidden, verificare che il chiamante abbia il ruolo Utente Foundry nella risorsa agente.

Aggiornamento degli agenti

Per implementare una nuova versione dell'agente:

  1. Apportare modifiche nell'ambiente di sviluppo e testare attentamente
  2. Nel portale di Foundry salvare la configurazione aggiornata dell'agente
  3. L'endpoint instrada automaticamente il traffico alla nuova versione

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

Generazione di codice di integrazione

Foundry Toolkit per 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'agente supportano attualmente solo l'API Responses senza stato. Archiviare la cronologia delle conversazioni nel client per esperienze a più turni.