evaluate API 接受 sessionSpans 清單，其中包含兩種類型的實體：跨度和事件
範圍和事件
評估服務會處理兩種遙測資料，以了解代理程式的行為和效能。
範圍
範圍包含個別操作的中繼資料，包括屬性、範圍資訊、時間戳記和資源識別符。跨度可在aws/spans日誌群組中使用。
事件
事件包含 body 欄位中的承載資訊，包括來自模型、工具和代理程式的輸入和輸出。對於在 AgentCore 執行期上託管的代理程式，事件會存放在/aws/bedrock-agentcore/runtimes/agent_id-endpoint_name日誌群組中。對於託管在 AgentCore 執行期之外的代理程式，事件會存放在OTEL_EXPORTER_OTLP_LOGS_HEADERS環境變數設定的日誌群組中。
若要評估工作階段，需要跨和對應的事件。並非所有跨度都會有事件，但具有支援範圍的事件應包含對應的事件，否則服務會擲回 ValidationException。
跨度結構
跨度遵循標準化結構，其中包含提供客服人員工作流程中操作內容的必要和選用欄位。
屬性變化
跨屬性中的資訊會根據使用的代理程式架構和檢測程式庫而有所不同。
支援的範圍
範圍名稱會決定服務是否可以處理跨度。目前支援以下範圍：
{
"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"
}
},
}
事件結構
跨度事件與使用 spanId和 traceId 的跨度相關聯。事件的範圍名稱用於判斷是否包含評估所需的資訊。
{
"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",
}
事件內文結構描述
對於具有支援範圍的事件， body 欄位會遵循此結構描述。內容欄位中的實際值會根據使用的架構和檢測程式庫而有所不同。
{
"body": {
"output": {
"messages": [
{
"content": "string/dict" # depends on framework/instrumentation
"role": "string"
}
]
},
"input": {
"messages": [
{
"content": "string/dict" # depends on framework/instrumentation
"role": "string"
}
]
}
}
}
範例範圍和事件
以下是範例，適用於依照入門指南在 AgentCore 執行期中建立和部署的示範代理程式及其對應的事件。這些範例示範了
-
用於追蹤層級評估的 InvokeAgent 範圍
-
用於工具層級評估的 ExecuteTool 範圍
範例
- Strands Agents
-
-
屬性"gen_ai.operation.name": "invoke_agent"用於識別代理程式叫用範圍
## 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)
-
-
屬性"traceloop.span.kind": "workflow"用於識別代理程式叫用範圍
{
"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
-
-
屬性"traceloop.span.kind": "tool"用於識別工具執行範圍
## 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"
}
}
}
