Instrumente a su agente Cómo se identifican los intervalos Cómo se extraen los campos de evaluación Ejemplos de intervalos en telemetría dividida Los ejemplos abarcan la telemetría unificada

Google ADK

En esta página se explica cómo configurar un agente del Kit de desarrollo de agentes de Google (ADK), cómo se identifican los intervalos y cómo se extraen los campos de evaluación.

Temas

Instrumenta a tu agente
Cómo se identifican los tramos
Cómo se extraen los campos de evaluación
- De los registros de eventos
- De los atributos de span
Ejemplo de intervalos en telemetría dividida
Ejemplos de intervalos en telemetría unificada

Instrumente a su agente

Puedes instrumentar un agente de Google ADK con la biblioteca de OpenInference instrumentación ()openinference-instrumentation-google-adk. Esta biblioteca emite telemetría con el nombre del ámbitoopeninference.instrumentation.google_adk, que lee Amazon Bedrock Evaluations. AgentCore

Cuando su agente se ejecuta con la AWS distribución para OpenTelemetry (ADOT), como en Amazon Bedrock AgentCore Runtime, no es necesario añadir código de instrumentación explícito. Basta con añadir la biblioteca de instrumentación a las dependencias de su proyecto. ADOT la descubre al inicio y la activa automáticamente.

Agregue la biblioteca de instrumentación a sus dependencias.

nota

Usa la versión 0.1.13 o posterior. Esta es la primera versión probada con el servicio de evaluación.

requirements.txt:


openinference-instrumentation-google-adk>=0.1.13

pyproject.toml:


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

nota

La instrumentación es un paso para configurar la observabilidad. Para exportar la telemetría para su evaluación, complete la configuración completa en Configurar la observabilidad.

Cómo se identifican los intervalos

Google ADK sigue la OpenInference convención, por lo que AgentCore Evaluations clasifica los intervalos mediante el atributo. openinference.span.kind

Tipo de intervalo	Atributo identificativo
Invocar al agente	`openinference.span.kind`= `CHAIN` o `AGENT`
Ejecutar herramienta	`openinference.span.kind` = `TOOL`
Inferencia	`openinference.span.kind` = `LLM`

Google ADK emite un árbol de intervalos anidado: un span () externo invocation envuelve un agent_run span (CHAINAGENT), que a su vez envuelve los intervalos () y call_llm (LLM). execute_tool TOOL El CHAIN intervalo exterior contiene el indicador del usuario; AgentCore Evaluations lo usa como el intervalo del agente de invocación.

Cómo se extraen los campos de evaluación

Google ADK envuelve el contenido de sus conversaciones en el formato de contenido Gemini. La solicitud de usuario está anidada debajo de un new_message objeto como {"new_message": {"parts": [{"text": "…"}], "role": "user"}} y la respuesta del agente está anidada debajo de un objeto como. content {"content": {"parts": [{"text": "…"}], "role": "model"}} AgentCore Las evaluaciones desenvuelven estas estructuras y unen el texto con líneas nuevas. parts Las definiciones de las herramientas llegan como una solicitud de Gemini serializada; AgentCore Evaluations lee las herramientas disponibles de. config.tools[].function_declarations[]

La ubicación de este contenido depende de cómo se recopiló la telemetría. El atributo de identificación (openinference.span.kind) está en el intervalo en ambos casos. Para obtener más información, consulte Configuración y entrega de telemetría.

De los registros de eventos

Con la telemetría dividida, AgentCore las evaluaciones leen el contenido del registro de eventos en relación con cada intervalo:

Mensaje del usuario: desde el registro de eventos del intervalo del agente invocador, en. body.input AgentCore Las evaluaciones desenvuelven el texto. new_message.parts
Respuesta del agente: del registro de eventos del intervalo del agente invocador, en. body.output AgentCore Las evaluaciones desenvuelven el texto. content.parts
Llamada a la herramienta: el nombre de la herramienta que aparece en el tool.name atributo del conjunto de herramientas de ejecución. Los argumentos y el resultado de la herramienta provienen del registro de eventos de ese intervalo, en body.input ybody.output.

Para obtener más información, consulte el ejemplo de intervalos en telemetría dividida.

A partir de los atributos de intervalo

Con la telemetría unificada, el mismo contenido permanece en el intervalo que los atributos:

Mensaje del usuario y respuesta del agente: desde input.value y hacia output.value el intervalo del agente que invoca. AgentCore Las evaluaciones desglosan el texto «y». new_message.parts content.parts
Llamada a la herramienta: el nombre de la herramienta detool.name, los argumentos y el resultado de input.value youtput.value, en el intervalo de herramientas de ejecución.

Para obtener más información, consulte Ejemplos de intervalos en telemetría unificada.

Ejemplos de intervalos en telemetría dividida

Con la telemetría dividida, el intervalo contiene los atributos de identificación y el contenido se encuentra en un registro de eventos correlacionado. Los siguientes ejemplos provienen de un agente de planificación de viajes de Google ADK implementado en Amazon Bedrock Runtime. AgentCore

nota

Estos ejemplos no son tramos completos. Muestran datos representativos de una interacción real con un agente; se omiten algunos campos y se truncan los valores largos para facilitar la lectura.

ejemplo

Invoke agent span

El openinference.span.kind atributo (CHAIN) del invocation intervalo exterior lo identifica como un intervalo del agente de invocación. El intervalo no contiene contenido de conversación; se encuentra en el registro de eventos correlacionados.


{
  "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"
  }
}

El registro de eventos correlacionados contiene la conversación. La solicitud de usuario está anidada debajo new_message.parts y la respuesta del agente está anidada debajo. 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

El openinference.span.kind atributo (TOOL) lo identifica como un conjunto de herramientas de ejecución; tool.name contiene el nombre de la herramienta. Los argumentos y el resultado de la herramienta se encuentran en el registro de eventos correlacionados.


{
  "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

El openinference.span.kind atributo (LLM) del call_llm intervalo lo identifica como un intervalo de inferencia. Contiene los metadatos del modelo y, en el índice llm.input_messages.* y los llm.output_messages.* atributos, los mensajes de la llamada al modelo.


{
  "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"
  }
}

Los ejemplos abarcan la telemetría unificada

Con la telemetría unificada, el mismo contenido permanece en los atributos del intervalo y no se produce ningún registro de eventos independiente. Los siguientes ejemplos provienen de un agente de planificación de viajes de Google ADK.

nota

Estos ejemplos no son tramos completos. Muestran datos representativos de una interacción real con un agente; se omiten algunos campos y se truncan los valores largos para facilitar la lectura.

ejemplo

Invoke agent span

El input.value atributo contiene la solicitud de usuario (anidada debajonew_message.parts) y la respuesta del output.value agente (anidada debajo). 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

El input.value atributo contiene los argumentos de la herramienta y el output.value resultado de la herramienta.


{
  "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

El openinference.span.kind atributo (LLM) del call_llm intervalo lo identifica como un intervalo de inferencia. Los mensajes de la llamada al modelo están en línea en los atributos indexados y. 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"
  }
}

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

LlamaIndex

SDK de Claude Agent