View a markdown version of this page

Comprendre les plages de saisie - Amazon Bedrock AgentCore
Spans et événementsExemples de durées et d'événements

Comprendre les plages de saisie

L'evaluateAPI accepte une liste de sessionSpans deux types d'entités : les spans et les événements

Spans et événements

Le service d'évaluation traite deux types de données de télémétrie pour comprendre le comportement et les performances de votre agent.

Spans

Les spans contiennent des métadonnées relatives à des opérations individuelles, notamment des attributs, des informations de portée, des horodatages et des identifiants de ressources. Les travées sont disponibles par groupe de aws/spans journaux.

Événements

Les événements contiennent des informations sur la charge utile body sur le terrain, notamment les entrées et sorties des modèles, des outils et de l'agent. Pour l'agent hébergé sur AgentCore Runtime, les événements sont stockés dans un groupe de /aws/bedrock-agentcore/runtimes/agent_id-endpoint_name journaux. Pour les agents hébergés en dehors de AgentCore Runtime, les événements sont stockés dans le groupe de journaux configuré par variable d'OTEL_EXPORTER_OTLP_LOGS_HEADERSenvironnement.

Note

Pour évaluer une session, les deux périodes et les événements correspondants sont requis. Tous les spans ne comporteront pas d'événements, mais ceux dont les étendues sont prises en charge doivent inclure les événements correspondants, sinon le service lancera un. ValidationException

Structure de travée

Les spans suivent une structure standardisée avec des champs obligatoires et facultatifs qui fournissent un contexte sur les opérations de votre flux de travail d'agent.

Variations d'attributs

Les informations présentes dans les attributs span varient en fonction de la structure de l'agent et de la bibliothèque d'instrumentation utilisées.

Éscopes pris en charge

Le nom de la portée détermine si le service peut traiter la portée. Les étendues suivantes sont actuellement prises en charge :

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

Structure d’évènements

Les événements Span sont associés aux spans à l'aide de spanId ettraceId. Le nom de la portée de l'événement est utilisé pour déterminer s'il contient les informations requises pour l'évaluation.

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

Schéma du corps de l'événement

Pour les événements dont les étendues sont prises en charge, le body champ suit ce schéma. Les valeurs réelles du champ de contenu varient en fonction du framework et de la bibliothèque d'instrumentation utilisés. 

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

Exemples de durées et d'événements

Vous trouverez ci-dessous des exemples de périodes et les événements correspondants pour l'agent de démonstration créé et déployé dans AgentCore Runtime, conformément au guide de démarrage. Les exemples montrent

  • InvokeAgent intervalles utilisés pour les évaluations du niveau de trace

  • ExecuteTool étendues utilisées pour les évaluations au niveau des outils

Exemple
Strands Agents

  1. L'attribut "gen_ai.operation.name": "invoke_agent" est utilisé pour identifier les durées d'invocation des agents

    ## 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. L'attribut "traceloop.span.kind": "workflow" est utilisé pour identifier les durées d'invocation des agents

    {
  "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. L'attribut "traceloop.span.kind": "tool" est utilisé pour identifier les durées d'exécution des outils

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