View a markdown version of this page

Configurazione e consegna della telemetria - Fondamento Amazon AgentCore
Imposta l'osservabilitàModalità di invio della telemetriaCosa legge il servizio da un intervalloRiferimentiAgenti di esempio

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Configurazione e consegna della telemetria

Il tuo agente emette intervalli che Amazon Bedrock AgentCore Evaluations utilizza per ricostruire ogni sessione. Per sapere come AgentCore rappresenta sessioni, tracce e intervalli, consulta Understand observability for agentic resources in. AgentCore

Per assegnare un punteggio a una sessione, il servizio ha bisogno del contenuto della conversazione: i prompt del modello, i completamenti del modello e gli input e gli output dello strumento. La collocazione dei contenuti dipende da come il tuo agente fornisce la telemetria, ed è ciò che spiega questa pagina.

Argomenti

Imposta l'osservabilità

La strumentazione del vostro agente è una parte della produzione di telemetria che il servizio di valutazione è in grado di leggere. Il tuo agente deve inoltre avere l'osservabilità abilitata, in modo che possa esportare la sua telemetria su Amazon. CloudWatch Completa questa procedura:

  1. Abilita Amazon Transaction Search. CloudWatch La valutazione lo richiede in entrambe le modalità di erogazione. Vedi Abilitazione AgentCore dell'osservabilità.

  2. Abilita l'osservabilità per il tuo agente, in base a dove lo ospiti:

  3. Verifica la modalità di consegna utilizzata dal tuo agente, in modo da sapere dove arriva la tua telemetria. Gli agenti creati il 20 luglio 2026 o successivamente utilizzano la telemetria unificata per impostazione predefinita, mentre gli agenti creati prima di tale data utilizzano la telemetria divisa. La telemetria unificata richiede la versione ADOT 0.18.0 o successiva (). aws-opentelemetry-distro>=0.18.0 Le versioni precedenti inviano intervalli al gruppo di log condiviso. aws/spans

    Per un agente su AgentCore Runtime, si cambia modalità con la variabile di UNIFIED_TRACES_DESTINATION_ENABLED ambiente: impostala su per la telemetria unificata o true per la telemetria divisa. false Per le variabili di ambiente, le autorizzazioni IAM e la procedura completa per ciascuna opzione di hosting, consulta Span destination for agent hosted in Amazon Bedrock runtime. AgentCore

La modifica della modalità di consegna non comporta lo spostamento della telemetria già fornita. AgentCore Gli intervalli più vecchi rimangono nel gruppo di log in cui sono stati scritti, quindi il servizio valuta ancora una sessione registrata prima della modifica.

Modalità di invio della telemetria

AgentCore fornisce la telemetria del tuo agente in una delle due modalità:

  • La telemetria unificata (consigliata) mantiene tutto unito. Gli attributi che supportano i payload del modello e le richieste e risposte degli strumenti rimangono invariati e tutta la telemetria dell'agente viene trasferita a un unico gruppo di log.

  • La telemetria divisa li separa. La AWS Distro for OpenTelemetry (ADOT) sposta questi attributi dallo span in record separati, che vanno a un gruppo di log diverso rispetto agli span.

AgentCore Le valutazioni leggono entrambe le modalità. Nel servizio di valutazione non è possibile scegliere tra di esse e gli stessi valutatori forniscono gli stessi risultati in entrambi i casi. Consigliamo la telemetria unificata, disponibile in tutte le regioni AWS commerciali in cui è disponibile Runtime. AgentCore

Telemetria unificata (consigliata)

Con la telemetria unificata, tutta la telemetria del tuo agente viene inviata a un gruppo di log. Gli intervalli vanno al flusso di log di quel gruppo di spans log, accanto ai log dell'agente e all'output della console. Lo span mantiene gli attributi che trasportano i payload del modello e le richieste e risposte degli strumenti, quindi il servizio legge tutto ciò di cui ha bisogno dall'intervallo stesso.

Telemetria unificata: ADOT invia ogni intervallo con il relativo contenuto a un gruppo di log

Il gruppo di log che contiene gli intervalli dipende da dove si ospita l'agente:

  • Su Amazon Bedrock AgentCore Runtime: il gruppo di log dell'agente,. /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> AgentCore lo configura per te.

  • Ospitato all'esterno AgentCore di Runtime: il gruppo di log a cui viene assegnato il nome nella variabile di OTEL_EXPORTER_OTLP_TRACES_HEADERS ambiente.

Mantenere gli intervalli e i log in un unico posto aiuta oltre la valutazione. Puoi esaminare insieme tracce e log, scrivere policy IAM ( AWS Identity and Access Management) e configurare la crittografia delle chiavi gestita dal cliente per un singolo agente e puoi esportare tutto ciò che un agente produce iscrivendoti a un gruppo di log.

Telemetria divisa

Con la telemetria divisa, ADOT elimina i grandi carichi utili. Man mano che esporta ogni intervallo, estrae gli attributi che contengono i payload del modello e le richieste e risposte dello strumento e li invia come record di eventi separati, lasciando all'intervallo i metadati e gli attributi più piccoli. I record degli eventi esistono solo in questa modalità e seguono la convenzione degli eventi. OpenTelemetry

Ogni record di evento rimanda al relativo intervallo tramite un traceId e condiviso e spanId il contenuto si trova nel recordbody, ad esempio in body.input.messages ebody.output.messages.

Telemetria divisa: ADOT invia gli intervalli aws/spans e i contenuti delle conversazioni al gruppo di log degli agenti come record di eventi

I due tipi di record vanno quindi in posti diversi:

  • Gli intervalli vanno al gruppo di aws/spans log condiviso. CloudWatch crea questo gruppo di log quando si attiva Transaction Search.

  • I record degli eventi vengono inseriti in un gruppo di log separato. In AgentCore Runtime, questo è il gruppo di log dell'agente, nel flusso di otel-rt-logs log, AgentCore che viene configurato automaticamente. AgentCore Fuori da Runtime, è il gruppo di log a cui viene assegnato il nome nella variabile di OTEL_EXPORTER_OTLP_LOGS_HEADERS ambiente.

Per valutare una sessione, il servizio legge gli intervalli aws/spans e li confronta con i relativi record di eventi.

Cosa legge il servizio da un intervallo

Per ogni intervallo di una sessione, il servizio esegue le seguenti operazioni:

  1. Calcola di che tipo di intervallo si tratta, in base agli attributi impostati dal framework. Un intervallo può essere un invoke agent span (l'esecuzione dell'agente di primo livello), un execute tool span (una singola chiamata allo strumento) o un inference span (una singola chiamata al modello).

  2. Legge i valori necessari, come il prompt dell'utente, la risposta dell'agente e gli input e gli output dello strumento. Ad esempio, il prompt dell'utente proviene dal messaggio del ruolo utente nell'input dell'agente e la risposta dell'agente proviene dal messaggio assistant-role nell'output dell'agente.

Gli attributi che identificano un intervallo rimangono sempre sull'intervallo, in entrambe le modalità di consegna. Viene spostato solo il contenuto della conversazione. La posizione del contenuto all'interno dell'intervallo dipende anche dalla libreria di strumentazione utilizzata: la maggior parte delle librerie lo registra come attributi di estensione e alcune lo associano all'intervallo come eventi. Per ogni libreria, le pagine relative al framework elencano gli attributi identificativi, indicano dove si trova il contenuto e mostrano gli intervalli di esempio per entrambe le modalità.

Riferimenti

AgentCore Le valutazioni si basano sulle seguenti specifiche: OpenTelemetry

Agenti di esempio

Gli esempi seguenti mostrano come strumentare un agente Strands ospitato all'esterno di Amazon Bedrock AgentCore Runtime. Ogni esempio esporta la telemetria in Amazon utilizzando ADOT. CloudWatch Si concentrano sulla configurazione dell'osservabilità piuttosto che sull'API di valutazione. Gli esempi utilizzano Strands, ma lo stesso modello di hosting ed esportazione della telemetria si applica ad altri framework supportati, come. LangGraph