Avvio rapido: Come tracciare l'agente ospitato

Nota

Il tracing è attualmente disponibile in anteprima.

In questo avvio rapido verranno visualizzate le tracce end-to-end per l'agente ospitato distribuito in Distribuzione del primo agente ospitato. Richiami il tuo agente per generare dati di tracciamento ed esaminare le tracce nel portale Foundry.

Le librerie di hosting (azure-ai-agentserver-responses e azure-ai-agentserver-invocations) integrano senza problemi la distribuzione Microsoft OpenTelemetry, che fornisce la strumentazione predefinita per Microsoft Agent Framework e LangChain ed esporta le tracce in Application Insights. Il servizio agente Foundry genera inoltre dati di telemetria sul lato server per la chiamata automatica dell'agente, senza che siano necessarie modifiche al codice.

La traccia offre visibilità sul modo in cui l'agente gestisce ogni richiesta in modo da poter eseguire il debug dei problemi, monitorare la latenza e comprendere il comportamento dell'agente prima di rilasciare le modifiche agli utenti.

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

  • Un agente ospitato distribuito e richiamabile da Distribuzione del primo agente ospitato e la directory del progetto azd creata in tale avvio rapido.

  • Il ruolo Utente Foundry nella risorsa Foundry.

  • Per usare il percorso tramite l'interfaccia utente, accedere al portale Foundry. Per il percorso azd, vedere i requisiti successivi.

  • Azure Developer CLI (azd) 1.27.1 o versione successiva con l'estensione azd microsoft.foundry :

    azd ext install microsoft.foundry

  • Sessione autenticata azd . Controllare lo stato con azd auth statused eseguire azd auth login se non si è connessi.

    Importante

    I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

  • Una risorsa di Application Insights Monitoraggio di Azure connessa al progetto Foundry. Per configurarla, vedere Configurare la traccia in Microsoft Foundry.

  • Il ruolo Lettore di Log Analytics nella risorsa di Application Insights collegata al tuo progetto. Se le tabelle di Log Analytics sottostanti sono protette, assegnare anche il ruolo Lettore dei dati di monitoraggio con privilegi.

Passaggio 1: Richiamare l'agente

Generare dati di traccia inviando una richiesta all'agente distribuito.

Dalla directory del azd progetto inviare una richiesta di test:

azd ai agent invoke "Summarize the benefits of distributed tracing for AI agents."

Verrà visualizzata una risposta entro pochi secondi.

Ogni chiamata genera una traccia completa. Per le tracce più complete, inviare richieste che attivano le chiamate dello strumento o il ragionamento a più turni.

Passaggio 2: Visualizza le tracce nel portale Foundry

Le tracce possono essere visualizzate nel portale Foundry dopo l'invocazione.

  1. Nel portale Foundry, apri il tuo progetto.
  2. Nella navigazione a sinistra, selezionare Agenti.
  3. Nella parte superiore selezionare Tracce.
  4. Trova la tua traccia nell'elenco. È possibile eseguire ricerche in base a ID traccia, ID risposta o filtrare in base all'intervallo di tempo.

Traiettoria

Schermata della visualizzazione a cascata della traccia nel portale Foundry che mostra gli span di invoke_agent, i completamenti delle chat e le richieste di token, con i dettagli di input e output sulla destra.

Visualizzazione utente

Animazione della vista utente delle tracce nel portale Foundry.

Tip

Se l'agente usa Microsoft Agent Framework, genera automaticamente i propri intervalli OpenTelemetry. Questi span vengono visualizzati come elementi figlio degli span del livello di hosting, fornendo una struttura di traccia completa dalla richiesta HTTP all'orchestrazione dell'agente, fino alle singole chiamate agli strumenti e alle interazioni con l'LLM.

Pulire le risorse

I dati di traccia vengono archiviati in Application Insights e seguono le impostazioni di conservazione dei dati dell'area di lavoro. Questa guida introduttiva non crea risorse aggiuntive. Per pulire la guida introduttiva precedente, eseguire azd down dalla directory del progetto agent. Ciò che il comando elimina dipende dal fatto che l'inizializzazione creata o riutilizzata il progetto Foundry.

Avvertimento

Se l'ambiente corrente azd ha creato il progetto Foundry, azd down elimina definitivamente il gruppo di risorse del progetto e tutti gli elementi in esso contenuti. Se è stato selezionato un progetto esistente durante l'inizializzazione, azd down lascia il progetto, il relativo gruppo di risorse, l'agente ospitato e altre risorse di avvio rapido sul posto. Per eliminare le risorse non più necessarie dal progetto esistente, eliminarle separatamente.

Troubleshooting

Issue Soluzione
Non si usano agenti ospitati di Foundry e le tracce non vengono visualizzate Questo avvio rapido illustra solo gli agenti ospitati. Per gli agenti di traccia ospitati all'esterno di Foundry, vedere Registrare un agente esterno.
Non viene visualizzata alcuna traccia dopo aver invocato l'agente Verificare che Application Insights sia connesso al progetto Foundry. Se non è abilitata, vedi Configurare il rilevamento in Microsoft Foundry. Verificare che l'agente abbia risposto correttamente con azd ai agent invoke.
Le tracce vengono visualizzate ma gli intervalli mancano attributi di dati di input/output Abilitare la registrazione del contenuto impostando la variabile OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true di ambiente nella configurazione dell'agente.
AuthorizationFailed quando si visualizzano tracce È necessario il ruolo Lettore di Log Analytics sulla risorsa Application Insights. Se le tabelle sono protette, assegnare anche Privileged Monitoring Data Reader.
Vengono visualizzate tracce ma mancano span di chiamata dello strumento Verificare che l'agente definisca gli strumenti e il modello li richiami durante la richiesta. Se si utilizza Microsoft Agent Framework, verificare che gli strumenti vengano registrati nel costruttore Agent tramite il parametro tools. Vedere Aggiungere strumenti all'agente.
Errore AuthenticationError o DefaultAzureCredential Aggiornare le credenziali con azd auth logout e quindi azd auth login.

Cosa si è appreso

Questo avvio rapido spiega come:

  • È stato osservato che le librerie di hosting integrano la distribuzione Microsoft OpenTelemetry per una strumentazione pronta all'uso.
  • Hai invocato il tuo agente distribuito per generare dati di traccia.
  • Visualizzare le tracce end-to-end nel portale Foundry.

Passaggi successivi

Configurare il tracciamento in Microsoft Foundry

Contenuti correlati

  • Ultimo aggiornamento: