View a markdown version of this page

Entendendo os intervalos de entrada - Amazon Bedrock AgentCore
Expansões e eventosExemplos de períodos e eventos

Entendendo os intervalos de entrada

A evaluate API aceita uma lista desessionSpans, que consiste em dois tipos de entidades: extensões e eventos

Expansões e eventos

O serviço de avaliação processa dois tipos de dados de telemetria para entender o comportamento e o desempenho do seu agente.

Segmentos

Os intervalos contêm metadados sobre operações individuais, incluindo atributos, informações de escopo, registros de data e hora e identificadores de recursos. Os vãos estão disponíveis no grupo de aws/spans registros.

Eventos

Os eventos contêm informações de carga útil no body campo, incluindo entradas e saídas de modelos, ferramentas e do agente. Para o agente hospedado no AgentCore Runtime, os eventos são armazenados no grupo de /aws/bedrock-agentcore/runtimes/agent_id-endpoint_name registros. Para agentes hospedados fora do AgentCore Runtime, os eventos são armazenados no grupo de registros configurado pela variável de OTEL_EXPORTER_OTLP_LOGS_HEADERS ambiente.

nota

Para avaliar uma sessão, são necessários os períodos e os eventos correspondentes. Nem todos os períodos terão eventos, mas aqueles com os escopos suportados devem incluir eventos correspondentes, caso contrário, o serviço lançará um. ValidationException

Estrutura do vão

Os spans seguem uma estrutura padronizada com campos obrigatórios e opcionais que fornecem contexto sobre as operações no fluxo de trabalho do seu agente.

Variações de atributos

As informações presentes nos atributos span variam com base na estrutura do agente e na biblioteca de instrumentação usada.

Escopos suportados

O nome do escopo determina se o serviço pode processar a extensão. Atualmente, há suporte para os seguintes escopos:

  • 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"
        }
    },
}

Estrutura de eventos

Os eventos de intervalo são associados a períodos usando spanId e. traceId O nome do escopo do evento é usado para determinar se ele contém as informações necessárias para avaliação.

{
    "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 do corpo do evento

Para eventos com escopos compatíveis, o body campo segue esse esquema. Os valores reais no campo de conteúdo variam de acordo com a estrutura e a biblioteca de instrumentação usadas. 

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

Exemplos de períodos e eventos

Abaixo estão exemplos de períodos e seus eventos correspondentes para o agente de demonstração criado e implantado no AgentCore Runtime de acordo com o guia de introdução. Os exemplos demonstram

  • InvokeAgent extensões usadas para avaliações de nível de traço

  • ExecuteTool vãos usados para avaliações de nível de ferramenta

exemplo
Strands Agents

  1. "gen_ai.operation.name": "invoke_agent"O atributo é usado para identificar os períodos de invocação do 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"O atributo é usado para identificar os períodos de invocação do 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"O atributo é usado para identificar períodos de execução da ferramenta

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