View a markdown version of this page

Comprensión de los intervalos de entrada - Amazon Bedrock AgentCore
Intervalos y eventosEjemplos de intervalos y eventos

Comprensión de los intervalos de entrada

La evaluate API acepta una lista desessionSpans, que consta de dos tipos de entidades: intervalos y eventos

Intervalos y eventos

El servicio de evaluación procesa dos tipos de datos de telemetría para comprender el comportamiento y el desempeño de su agente.

Intervalos

Los intervalos contienen metadatos sobre las operaciones individuales, incluidos los atributos, la información sobre el alcance, las marcas de tiempo y los identificadores de recursos. Los intervalos están disponibles en grupos de registros. aws/spans

Events (Eventos)

Los eventos contienen información sobre la carga útil en el body campo, incluidas las entradas y salidas de los modelos, las herramientas y el agente. En el caso de los agentes alojados en AgentCore Runtime, los eventos se almacenan en un grupo de /aws/bedrock-agentcore/runtimes/agent_id-endpoint_name registros. En el caso de los agentes alojados fuera AgentCore de Runtime, los eventos se almacenan en el grupo de registros configurado por variable de OTEL_EXPORTER_OTLP_LOGS_HEADERS entorno.

nota

Para evaluar una sesión, se requieren tanto los intervalos como los eventos correspondientes. No todos los intervalos tendrán eventos, pero los que tengan los alcances compatibles deberían incluir los eventos correspondientes; de lo contrario, el servicio generará un. ValidationException

Estructura de intervalos

Los intervalos siguen una estructura estandarizada con campos obligatorios y opcionales que proporcionan un contexto sobre las operaciones del flujo de trabajo del agente.

Variaciones de atributos

La información presente en los atributos de span varía según la estructura del agente y la biblioteca de instrumentación utilizadas.

Ámbitos compatibles

El nombre del ámbito determina si el servicio puede procesar el intervalo. Actualmente se admiten los siguientes ámbitos:

  • strands.telemetry.tracer

  • opentelemetry.instrumentation.langchain

  • openinference.instrumentation.langchain 

{
    "spanId": "string"                 ## required
    "traceId": "string",               ## required
    "parentSpanId": "string",
    "name": "string"                   ## required
    "scope": {
        "name": "string"               ## required
    },
    "startTimeUnixNano": "epoch time", ## required
    "endTimeUnixNano": "epoch time",   ## required
    "durationNano": "epoch time",
    "attributes": {                    ## required
        "session.id": "string",        ## required
        "string": "string"
    },
    "status": {
        "code": "string"
    },
    "kind": "string",
    "resource": {
        "attributes": {
            "string": "string",
            "string": "string"
        }
    },
}

Estructura de evento

Los eventos de intervalo se asocian a los intervalos mediante spanId y. traceId El nombre del ámbito del evento se utiliza para determinar si contiene la información necesaria para la evaluación.

{
    "spanId": "string",         ## required
    "traceId": "string",        ## required
    "scope": {
        "name": "string"        ## required
    },
    "body": "Any",              ## required for supported scopes (refer below section)
    "attributes": {
        "event.name": "string", ## required
        "session.id": "string"  ## required
    },
    "resource": {
        "attributes": {
            "string": "string",
            "string": "string"
        }
    },
    "timeUnixNano": "epoch time",
    "observedTimeUnixNano": "epoch time",
    "severityNumber": "int",
    "severityText": "string",
}

Esquema del cuerpo del evento

Para los eventos con ámbitos compatibles, el body campo sigue este esquema. Los valores reales del campo de contenido varían según el marco y la biblioteca de instrumentación utilizados. 

{
    "body": {
        "output": {
            "messages": [
                {
                    "content": "string/dict" # depends on framework/instrumentation
                    "role": "string"
                }
            ]
        },
        "input": {
            "messages": [
                {
                    "content": "string/dict" # depends on framework/instrumentation
                    "role": "string"
                }
            ]
        }
    }
}

Ejemplos de intervalos y eventos

A continuación, se muestran ejemplos de intervalos y sus eventos correspondientes para el agente de demostración creado e implementado en AgentCore Runtime según la guía de introducción. Los ejemplos demuestran

  • InvokeAgent intervalos utilizados para las evaluaciones a nivel de trazas

  • ExecuteTool intervalos utilizados para las evaluaciones a nivel de herramienta

ejemplo
Strands Agents

  1. "gen_ai.operation.name": "invoke_agent"El atributo se utiliza para identificar los intervalos de invocación del agente

    ## Example invoke_agent span for strands agent
{
  "spanId": "e79d2156ac138f63",
  "traceId": "691e400b638f5225711e80da37a4b0bd",
  "resource": {
      "attributes": {
          "deployment.environment.name": "bedrock-agentcore:default",
          "aws.local.service": "agentcore_evaluation_demo.DEFAULT",
          "service.name": "agentcore_evaluation_demo.DEFAULT",
          "cloud.region": "us-east-1",
          "aws.log.stream.names": "otel-rt-logs",
          "telemetry.sdk.name": "opentelemetry",
          "aws.service.type": "gen_ai_agent",
          "telemetry.sdk.language": "python",
          "cloud.provider": "aws",
          "cloud.resource_id": "agent-arn",
          "aws.log.group.names": "/aws/bedrock-agentcore/runtimes/agent-id",
          "telemetry.sdk.version": "1.33.1",
          "cloud.platform": "aws_bedrock_agentcore",
          "telemetry.auto.version": "0.12.2-aws"
      }
  },
  "scope": {
      "name": "strands.telemetry.tracer",
      "version": ""
  },

  "parentSpanId": "ec3c4c7fb2603f7a",
  "flags": 256,
  "name": "invoke_agent Strands Agents",
  "kind": "INTERNAL",
  "startTimeUnixNano": 1763590155895947177,
  "endTimeUnixNano": 1763590165204959446,
  "durationNano": 9309012269,
  "attributes": {
      "aws.local.service": "agentcore_evaluation_demo.DEFAULT",
      "gen_ai.usage.prompt_tokens": 2021,
      "gen_ai.usage.output_tokens": 320,
      "gen_ai.usage.cache_write_input_tokens": 0,
      "gen_ai.agent.name": "Strands Agents",
      "gen_ai.usage.total_tokens": 2341,
      "gen_ai.usage.completion_tokens": 320,
      "gen_ai.event.start_time": "2025-11-19T22:09:15.895962+00:00",
      "aws.local.environment": "bedrock-agentcore:default",
      "gen_ai.operation.name": "invoke_agent",
      "gen_ai.event.end_time": "2025-11-19T22:09:25.204930+00:00",
      "gen_ai.usage.input_tokens": 2021,
      "gen_ai.request.model": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
      "gen_ai.usage.cache_read_input_tokens": 0,
      "gen_ai.agent.tools": "[\"analyze_text\", \"get_word_frequency\"]",
      "PlatformType": "AWS::BedrockAgentCore",
      "session.id": "test-ace-demo-session-18a1dba0-62a0-462g",
      "gen_ai.system": "strands-agents",
      "gen_ai.tool.definitions": "[{\"name\": \"analyze_text\", \"description\": \"Analyze text and provide statistics about it.\", \"inputSchema\": {\"json\": {\"properties\": {\"text\": {\"description\": \"Parameter text\", \"type\": \"string\"}}, \"required\": [\"text\"], \"type\": \"object\"}}, \"outputSchema\": null}, {\"name\": \"get_word_frequency\", \"description\": \"Get the frequency of words in the provided text.\", \"inputSchema\": {\"json\": {\"properties\": {\"text\": {\"description\": \"Parameter text\", \"type\": \"string\"}, \"top_n\": {\"default\": 5, \"description\": \"Parameter top_n\", \"type\": \"integer\"}}, \"required\": [\"text\"], \"type\": \"object\"}}, \"outputSchema\": null}]"
  },
  "status": {
      "code": "OK"
  }
}
Langgraph (with opentelemetry-instrumentation)

  1. "traceloop.span.kind": "workflow"El atributo se utiliza para identificar los intervalos de invocación del agente

    {
  "resource": {
    "attributes": {
      "deployment.environment.name": "bedrock-agentcore:default",
      "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
      "service.name": "agentcore_evaluation_demo_lg.DEFAULT",
      "cloud.region": "us-east-1",
      "aws.log.stream.names": "otel-rt-logs",
      "telemetry.sdk.name": "opentelemetry",
      "aws.service.type": "gen_ai_agent",
      "telemetry.sdk.language": "python",
      "cloud.provider": "aws",
      "cloud.resource_id": "<agent-arn>",
      "aws.log.group.names": "/aws/bedrock-agentcore/runtimes/<agent-id>",
      "telemetry.sdk.version": "1.33.1",
      "cloud.platform": "aws_bedrock_agentcore",
      "telemetry.auto.version": "0.14.0-aws"
    }
  },
  "scope": {
    "name": "opentelemetry.instrumentation.langchain",
    "version": "0.48.1"
  },
  "traceId": "691f4a5c0a7ab761407a1a9a36991613",
  "spanId": "298f3169bdca46d8",
  "parentSpanId": "737921ed52222e5d",
  "flags": 256,
  "name": "LangGraph.workflow",
  "kind": "INTERNAL",
  "startTimeUnixNano": 1763658333042983700,
  "endTimeUnixNano": 1763658340533358800,
  "durationNano": 7490375269,
  "attributes": {
    "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
    "traceloop.span.kind": "workflow",
    "traceloop.workflow.name": "LangGraph",
    "traceloop.entity.name": "LangGraph",
    "PlatformType": "AWS::BedrockAgentCore",
    "session.id": "test-ace-demo-session-18a1dba0-62a0-462g",
    "traceloop.entity.path": "",
    "aws.local.environment": "bedrock-agentcore:default"
  },
  "status": {
    "code": "UNSET"
  }
}
ExecuteTool span

  1. "traceloop.span.kind": "tool"El atributo se utiliza para identificar los intervalos de ejecución de la herramienta

    ## tool span
{
  "traceId": "691f4a5c0a7ab761407a1a9a36991613",
  "spanId": "b58bd6568e00fc64",
  "parentSpanId": "aaee94b5bd16f3b0",
  "scope": {
    "name": "opentelemetry.instrumentation.langchain",
    "version": "0.48.1"
  },
  "flags": 256,
  "name": "get_word_frequency.tool",
  "kind": "INTERNAL",
  "startTimeUnixNano": 1763658336583727000,
  "endTimeUnixNano": 1763658336584260400,
  "durationNano": 533416,
  "attributes": {
    "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
    "traceloop.span.kind": "tool",
    "traceloop.workflow.name": "LangGraph",
    "traceloop.entity.name": "get_word_frequency",
    "PlatformType": "AWS::BedrockAgentCore",
    "session.id": "test-ace-demo-session-18a1dba0-62a0-462g",
    "traceloop.entity.path": "tools",
    "aws.local.environment": "bedrock-agentcore:default"
  },
  "status": {
    "code": "UNSET"
  },
  "resource": {
    "attributes": {
      "deployment.environment.name": "bedrock-agentcore:default",
      "aws.local.service": "agentcore_evaluation_demo_lg.DEFAULT",
      "service.name": "agentcore_evaluation_demo_lg.DEFAULT",
      "cloud.region": "us-east-1",
      "aws.log.stream.names": "otel-rt-logs",
      "telemetry.sdk.name": "opentelemetry",
      "aws.service.type": "gen_ai_agent",
      "telemetry.sdk.language": "python",
      "cloud.provider": "aws",
      "cloud.resource_id": "<agent-arn>",
      "aws.log.group.names": "/aws/bedrock-agentcore/runtimes/<agent-id>",
      "telemetry.sdk.version": "1.33.1",
      "cloud.platform": "aws_bedrock_agentcore",
      "telemetry.auto.version": "0.14.0-aws"
    }
  }
}