Individua il tuo agente Come vengono identificati gli intervalli Come vengono estratti i campi di valutazione Esempi di intervalli nella telemetria divisa Esempi di intervalli di telemetria unificata

Google ADK

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

Argomenti

Individua il tuo agente
Come vengono identificati gli intervalli
Come vengono estratti i campi di valutazione
- Dai registri degli eventi
- Dagli attributi span
Esempi di intervalli nella telemetria divisa
Esempi di intervalli nella telemetria unificata

Individua il tuo agente

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

Quando l'agente viene eseguito con 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 verso l'impostazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità. Imposta l'osservabilità

Come vengono identificati gli intervalli

Google ADK è basato sulla OpenInference convenzione, quindi AgentCore Evaluations classifica gli intervalli 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 avvolge invocation uno span (CHAIN), che a sua volta avvolge gli AGENT intervalli () e (). agent_run call_llm LLM execute_tool TOOL L'CHAINintervallo esterno contiene il prompt dell'utente; Evaluations lo utilizza come intervallo dell'agente di invocazione. AgentCore

Come vengono estratti i campi di valutazione

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

La posizione di questo contenuto dipende da come è stata raccolta la telemetria. L'attributo identificativo (openinference.span.kind) si trova nello span in entrambi i casi. Per ulteriori informazioni, vedere Configurazione e consegna della telemetria.

Dai registri degli eventi

Con la telemetria divisa, AgentCore Evaluations legge il contenuto del record dell'evento correlato a ciascun intervallo:

Prompt utente: dal record degli eventi dell'agente invoke span, in. body.input AgentCore Le valutazioni estraggono il testo. new_message.parts
Risposta dell'agente: dal record degli eventi dell'agente invoke span, in. body.output AgentCore Le valutazioni estraggono il testo. content.parts
Chiamata allo strumento: il nome dello strumento derivato dall'tool.nameattributo nell'intervallo di esecuzione dello strumento. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in body.input e. body.output

Per ulteriori informazioni, consulta Esempi di intervalli di telemetria divisa.

Dagli attributi span

Con la telemetria unificata, lo stesso contenuto rimane nello span degli attributi:

Richiesta dell'utente e risposta dell'agente: da input.value e verso l'intervallo dell'agente output.value invoke. AgentCore Le valutazioni estraggono il testo e. new_message.parts content.parts
Chiamata allo strumento: il nome dello strumento datool.name, gli argomenti e il risultato da input.value e sull'intervallo di output.value esecuzione dello strumento.

Per ulteriori informazioni, consulta Esempi di intervalli nella telemetria unificata.

Esempi di intervalli nella telemetria divisa

Con la telemetria divisa, l'intervallo riporta gli attributi identificativi e il contenuto risiede in un record di eventi correlato. Gli esempi seguenti 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 di 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. L'intervallo non contiene contenuti di 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 in e new_message.parts la risposta dell'agente è annidata in. 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 un intervallo di esecuzione dello strumento; tool.name contiene il nome dello strumento. Gli argomenti e i risultati dello strumento sono presenti nel record dell'evento 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) sull'call_llmintervallo lo identifica come intervallo di inferenza. Contiene i metadati del modello e, negli indici e negli llm.output_messages.* attributi, i messaggi per la chiamata llm.input_messages.* 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"
  }
}

Esempi di intervalli di telemetria unificata

Con la telemetria unificata, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di evento separato. I seguenti esempi sono tratti da un agente di pianificazione dei viaggi di Google ADK.

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi di 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 (annidato sottonew_message.parts) e l'output.valueattributo contiene la risposta dell'agente (annidata 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) sull'call_llmintervallo lo identifica come intervallo di inferenza. I messaggi per la chiamata al modello sono in linea nell'indice e negli attributi. 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