View a markdown version of this page

Strands Agents - Amazon Bedrock AgentCore
Instrumente a su agenteCómo se identifican los intervalosCómo se extraen los campos de evaluaciónUn ejemplo de tramos con registros de eventosEl ejemplo abarca espacios sin registros de eventos

Strands Agents

Esta página explica cómo instrumentar un agente de Strands Agents, cómo se identifican los intervalos y cómo se extraen los campos de evaluación.

Temas

Instrumente a su agente

El SDK de Strands Agents incluye telemetría integrada y no requiere ninguna biblioteca de instrumentación adicional. Genera intervalos y registros de eventos con el nombre del ámbito. strands.telemetry.tracer Cuando se implementa en Amazon Bedrock AgentCore Runtime con AWS Distro for OpenTelemetry (ADOT), Runtime inyecta el session.id atributo y exporta los intervalos y los registros de eventos automáticamente.

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

Strands establece el gen_ai.operation.name atributo en cada tramo. El servicio de evaluación utiliza este atributo para clasificar los tramos:

Tipo de tramo Atributo identificativo Ejemplo de nombre de tramo

Invoca al agente

gen_ai.operation.name = invoke_agent

invoke_agent TravelAgent

Ejecute la herramienta

gen_ai.operation.name = execute_tool

execute_tool search_flights

Inferencia

gen_ai.operation.name = chat

chat

Cómo se extraen los campos de evaluación

La ubicación del contenido de la conversación depende de cómo se recopiló la telemetría. Cuando ADOT divide la telemetría, el contenido se encuentra en un registro de eventos independiente. Cuando la telemetría no está dividida, el contenido permanece en el intervalo como eventos en línea. Para obtener más información, consulte Intervalos, registros de eventos y señales de telemetría. El atributo de identificación (gen_ai.operation.name) está en el intervalo en ambos casos.

De los registros de eventos

Cuando se divide la telemetría, el servicio lee el contenido del registro de eventos correlacionado con cada intervalo:

  • Mensaje de usuario: a partir de los mensajes de entrada del agente (input.messages), el contenido del mensaje con un rol de usuario.

  • Respuesta del agente: a partir de los mensajes de salida del agente (output.messages), el contenido del mensaje con una función de asistente.

  • Llamada de herramienta: el nombre de la herramienta a partir del gen_ai.tool.name atributo del intervalo de herramientas de ejecución. Los argumentos y el resultado de la herramienta provienen del registro de eventos de ese intervalo (inputyoutput).

Para ver ejemplos, consulte Ejemplos de intervalos con registros de eventos.

A partir de eventos de intervalo en línea

Cuando la telemetría no está dividida, se incluye el mismo contenido en los eventos de extensión en línea en lugar de en un registro de eventos independiente:

  • Solicitud de usuario: del gen_ai.user.message evento, el atributo. content

  • Respuesta del agente: a partir del gen_ai.choice evento, el message atributo.

  • Llamada de herramienta: el nombre de la herramienta que gen_ai.tool.name aparece en el atributo del intervalo. Los argumentos de la herramienta provienen del gen_ai.tool.message evento y el resultado proviene del gen_ai.choice evento.

Para ver ejemplos, consulte Ejemplos de intervalos sin registros de eventos.

Un ejemplo de tramos con registros de eventos

Cuando se divide la telemetría, el intervalo contiene los atributos de identificación y el contenido reside en un registro de eventos correlacionado. Los siguientes ejemplos provienen de un agente de planificación de viajes de Strands implementado en Amazon Bedrock AgentCore Runtime.

nota

Estos ejemplos no son períodos completos. Muestran datos representativos de una interacción real entre agentes, omitiendo algunos campos y truncando los valores largos para facilitar la lectura.

ejemplo
Invoke agent span

El gen_ai.operation.name atributo (invoke_agent) lo identifica como un intervalo de agentes de invocación. El gen_ai.agent.tools atributo enumera las herramientas disponibles para el agente.

{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d24936b8989b6d42",
  "parentSpanId": "0ff3498548044e4b",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929864011990383,
  "endTimeUnixNano": 1776929869634304466,
  "durationNano": 5622314083,
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.system": "strands-agents",
    "gen_ai.agent.name": "TravelAgent",
    "gen_ai.request.model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
    "gen_ai.usage.input_tokens": 983,
    "gen_ai.usage.output_tokens": 232,
    "gen_ai.usage.total_tokens": 1215,
    "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

El registro de eventos correlacionados contiene el contenido de la conversación. El mensaje de usuario es el mensaje del rol de usuario y la respuesta del agente es el mensaje del rol de asistente. input.messages output.messages

{
  "spanId": "d24936b8989b6d42",
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "Hey, how can you help me"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "Hi there! I'm your travel planning assistant ...",
            "finish_reason": "end_turn"
          }
        }
      ]
    }
  }
}
Execute tool span

El gen_ai.operation.name atributo (execute_tool) lo identifica como un intervalo de herramientas de ejecución. El gen_ai.tool.name atributo contiene el nombre de la herramienta.

{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "fff785ce12d6fda8",
  "parentSpanId": "96915bf5ecc78743",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929872258292842,
  "endTimeUnixNano": 1776929872259611427,
  "durationNano": 1318585,
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_hiWwdtThuD67G5cK8cp5mj",
    "gen_ai.tool.status": "success",
    "gen_ai.tool.description": "Search for available flights between cities.",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

El registro de eventos correlacionados contiene la entrada (argumentos) y la salida (resultado) de la herramienta.

{
  "spanId": "fff785ce12d6fda8",
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "tool",
          "content": {
            "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
            "role": "tool",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    }
  }
}

El ejemplo abarca espacios sin registros de eventos

Cuando la telemetría no está dividida, el mismo contenido se incluye en los eventos de intervalo en línea del intervalo, sin registro de eventos independiente. Los siguientes ejemplos son de un agente de planificación de viajes de Strands.

nota

Estos ejemplos no son tramos completos. Muestran datos representativos de una interacción real entre agentes, omitiendo algunos campos y truncando los valores largos para facilitar la lectura.

ejemplo
Invoke agent span

El gen_ai.user.message evento contiene el mensaje del usuario y el gen_ai.choice evento contiene la respuesta del agente.

{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d2ee0e4765cc773e",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "TravelAgent",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.user.message",
      "attributes": {
        "content": "[{\"text\": \"Hey, how can you help me\"}]"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "Hi there! I'm your travel planning assistant ...",
        "finish_reason": "end_turn"
      }
    }
  ]
}
Execute tool span

El gen_ai.tool.message evento contiene los argumentos de la herramienta y el gen_ai.choice evento contiene el resultado de la herramienta.

{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "0a988e27758ebb53",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_JuGterOaZfQV2c55Rp3S7C",
    "gen_ai.tool.status": "success",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.tool.message",
      "attributes": {
        "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
        "role": "tool",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    }
  ]
}