Strumenta il tuo agente Come vengono identificati gli intervalli Come vengono estratti i campi di valutazione L'esempio si estende ai record degli eventi L'esempio si estende senza record di eventi

Google ADK

Questa pagina spiega come strumentare un agente Google Agent Development Kit (ADK), come vengono identificati gli intervalli e come vengono estratti i campi di valutazione.

Argomenti

Strumenta il tuo agente
Come vengono identificate le campate
Come vengono estratti i campi di valutazione
- Dai registri degli eventi
- Dagli attributi span
L'esempio include i record degli eventi
Esempio di intervalli senza record di eventi

Strumenta il tuo agente

Puoi strumentare un agente Google ADK con la libreria di OpenInferencestrumentazione (). openinference-instrumentation-google-adk Questa libreria emette dati di telemetria con il nome dell'ambito, letto da Amazon openinference.instrumentation.google_adk Bedrock Evaluations. AgentCore

Quando il tuo agente utilizza AWS Distro for OpenTelemetry (ADOT), ad esempio su Amazon Bedrock AgentCore Runtime, non è necessario aggiungere codice di strumentazione esplicito. È sufficiente aggiungere la libreria di strumentazione alle dipendenze del progetto. ADOT la rileva all'avvio e la attiva automaticamente.

Aggiungi la libreria di strumentazione alle tue dipendenze.

Nota

Usa la versione 0.1.13 o successiva. Questa è la prima versione testata con il servizio di valutazione.

requirements.txt:


openinference-instrumentation-google-adk>=0.1.13

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-google-adk>=0.1.13",
]

Nota

La strumentazione è un passo nella configurazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.

Come vengono identificati gli intervalli

Google ADK utilizza questa OpenInference convenzione, quindi Evaluations classifica gli intervalli AgentCore utilizzando l'attributo. openinference.span.kind

Tipo di intervallo	Attributo identificativo
Invoca l'agente	`openinference.span.kind`= `CHAIN` o `AGENT`
Strumento di esecuzione	`openinference.span.kind` = `TOOL`
Inferenza	`openinference.span.kind` = `LLM`

Google ADK emette uno span tree annidato: uno span esterno (CHAIN) avvolge invocation uno span (), che a sua volta racchiude gli agent_run span (AGENT) e (). call_llm LLM execute_tool TOOL L'outer CHAIN span contiene il prompt dell'utente; Evaluations lo utilizza come invoke agent span. AgentCore

Come vengono estratti i campi di valutazione

Google ADK inserisce i contenuti delle conversazioni nel formato di contenuti Gemini. Il prompt utente è annidato sotto un new_message oggetto come{"new_message": {"parts": [{"text": "…"}], "role": "user"}}, e la risposta dell'agente è annidata sotto un oggetto come. content {"content": {"parts": [{"text": "…"}], "role": "model"}} AgentCore Evaluations elimina queste strutture e unisce il testo con delle nuove righe. parts Le definizioni degli strumenti arrivano come richiesta Gemini serializzata; AgentCore Evaluations legge gli strumenti disponibili da. config.tools[].function_declarations[]

La posizione di questo contenuto dipende da come è stata raccolta la telemetria. L'attributo identificativo (openinference.span.kind) è compreso nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta Spans, record di eventi e segnali di telemetria.

Dai registri degli eventi

Quando la telemetria viene suddivisa, AgentCore Evaluations legge il contenuto del record dell'evento correlato a ciascun intervallo:

Richiesta utente: dal record degli eventi di Invoke Agent Span, in. body.input AgentCore Evaluations cancella il testo. new_message.parts
Risposta dell'agente: dal record degli eventi dell'agente invoke span, in. body.output AgentCore Evaluations cancella il testo. content.parts
Richiamata dello strumento: il nome dello strumento dall'tool.nameattributo nell'intervallo dello strumento di esecuzione. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in body.input and. body.output

Per esempi, vedete Example spans with event records.

Dagli attributi span

Quando la telemetria non viene suddivisa, lo stesso contenuto rimane nell'intervallo degli attributi:

Richiesta dell'utente e risposta dell'agente: da input.value e output.value sull'intervallo dell'agente Invoke. AgentCore Evaluations cancella il testo and. new_message.parts content.parts
Richiamata dello strumento: il nome dello strumento datool.name, gli argomenti e il risultato di input.value eoutput.value, nell'intervallo dello strumento di esecuzione.

Ad esempio, vedete Example spans without event records.

L'esempio si estende ai record degli eventi

Quando la telemetria viene suddivisa, l'intervallo contiene gli attributi identificativi e il contenuto risiede in un record di eventi correlato. I seguenti esempi sono tratti da un agente di pianificazione dei viaggi di Google ADK distribuito su Amazon Bedrock Runtime. AgentCore

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio

Invoke agent span

L'openinference.span.kindattributo (CHAIN) sullo span esterno lo identifica come invocation un invoke agent span. Lo span non contiene alcun contenuto della conversazione; risiede nel record dell'evento correlato.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "70f2e87a30c34420",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "user.id": "default_user",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

Il record dell'evento correlato contiene la conversazione. Il prompt dell'utente è annidato sotto new_message.parts e la risposta dell'agente è annidata sotto. content.parts


{
  "spanId": "70f2e87a30c34420",
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "{\"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}, \"state_delta\": null, \"run_config\": null}"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you with your travel plans! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}"
        }
      ]
    }
  }
}

Execute tool span

L'openinference.span.kindattributo (TOOL) lo identifica come estensione dello strumento di esecuzione; tool.name contiene il nome dello strumento. Gli argomenti e i risultati dello strumento risiedono nel record degli eventi correlato.


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "9028a8dd94943456",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "FunctionTool",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "9028a8dd94943456",
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}"
        }
      ]
    }
  }
}

Inference span

L'openinference.span.kindattributo (LLM) sullo call_llm span lo identifica come un intervallo di inferenza. Contiene i metadati del modello e, negli indici e negli llm.output_messages. attributi, i messaggi per la llm.input_messages. chiamata al modello.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "1c4e5f8a2b9d0e73",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

L'esempio si estende senza record di eventi

Quando la telemetria non viene suddivisa, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di eventi separato. Gli esempi seguenti sono tratti da un agente di pianificazione viaggi di Google ADK.

Nota

Questi esempi non sono esempi completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio

Invoke agent span

L'input.valueattributo contiene il prompt dell'utente (nidificato sottonew_message.parts) e l'output.valueattributo contiene la risposta dell'agente (nidificata sotto). content.parts


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "31ea3d5882dac680",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.value": "{\"user_id\": \"test_user\", \"session_id\": \"sea-nyc-trip-2-turns-google-adk-unified\", \"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}}",
    "input.mime_type": "application/json",
    "output.value": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you plan your trip! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

L'input.valueattributo contiene gli argomenti dello strumento e l'output.valueattributo contiene il risultato dello strumento.


{
  "traceId": "6a4de7c376913db82e6f0f336a16731d",
  "spanId": "b64c37adefae74f0",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

L'openinference.span.kindattributo (LLM) sullo call_llm span lo identifica come un intervallo di inferenza. I messaggi per la chiamata al modello sono in linea negli attributi indicizzati e. llm.input_messages. llm.output_messages.


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "2d5f6a9b3c0e1f84",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

LlamaIndex

Claude Agent SDK