Strands 代理程式
此頁面說明如何檢測 Strands Agents 代理程式、如何識別範圍，以及如何擷取評估欄位。
主題
檢測您的代理程式
Strands Agents SDK 包含內建遙測，不需要額外的檢測程式庫。它會在範圍名稱 下產生範圍和事件記錄strands.telemetry.tracer。使用 AWS Distro for OpenTelemetry (ADOT) 部署在 Amazon Bedrock AgentCore 執行期時，執行期會自動插入session.id屬性並匯出範圍和事件記錄。
如何識別跨度
字串會在每個範圍上設定 gen_ai.operation.name 屬性。評估服務使用此屬性來分類跨度：
| 跨度類型 |
識別屬性 |
範例跨度名稱 |
|
叫用代理程式
|
gen_ai.operation.name = invoke_agent
|
invoke_agent TravelAgent
|
|
執行工具
|
gen_ai.operation.name = execute_tool
|
execute_tool search_flights
|
|
Inference
|
gen_ai.operation.name = chat
|
chat
|
如何擷取評估欄位
對話內容的位置取決於收集遙測的方式。當 ADOT 分割遙測時，內容會位於單獨的事件記錄中。未分割遙測時，內容會保留在跨度上做為內嵌事件。如需詳細資訊，請參閱跨度、事件記錄和遙測訊號。在這兩種情況下，識別屬性 (gen_ai.operation.name) 位於跨度。
從事件記錄
分割遙測時，服務會從與每個範圍相關的事件記錄中讀取內容：
-
使用者提示：從客服人員輸入訊息 (input.messages)，使用使用者角色的訊息內容。
-
客服人員回應：來自客服人員輸出訊息 (output.messages)，訊息內容與 助理角色。
-
工具呼叫：執行工具範圍上 gen_ai.tool.name 屬性的工具名稱。工具引數和結果來自該範圍的事件記錄 (input 和 output)。
如需範例，請參閱範例跨越事件記錄。
從內嵌跨度事件
未分割遙測時，相同的內容會在內嵌跨度事件中傳送，而不是單獨的事件記錄：
-
使用者提示：來自 gen_ai.user.message事件的 content 屬性。
-
客服人員回應：來自 gen_ai.choice事件的 message 屬性。
-
工具呼叫：來自跨度上 gen_ai.tool.name 屬性的工具名稱。工具引數來自gen_ai.tool.message事件，而結果來自gen_ai.choice事件。
如需範例，請參閱沒有事件記錄的範例跨度。
範例跨越事件記錄
分割遙測時，範圍會攜帶識別屬性，而內容會存在於相關事件記錄中。下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 Strands 行程規劃代理程式。
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
範例
- Invoke agent span
-
gen_ai.operation.name 屬性 (invoke_agent) 將此識別為調用代理程式範圍。gen_ai.agent.tools 屬性會列出代理程式可用的工具。
{
"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"
}
}
相關事件記錄會攜帶對話內容。使用者提示是 中的使用者角色訊息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
-
gen_ai.operation.name 屬性 (execute_tool) 將此識別為執行工具範圍。gen_ai.tool.name 屬性會保留工具名稱。
{
"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"
}
}
相關事件記錄會攜帶工具輸入 （引數） 和輸出 （結果）。
{
"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"
}
}
]
}
}
}
沒有事件記錄的範例範圍
未分割遙測時，相同的內容會在跨度的內嵌跨度事件中傳送，沒有單獨的事件記錄。下列範例來自 Strands 旅行規劃代理程式。
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
範例
- Invoke agent span
-
gen_ai.user.message 事件會保留使用者提示，而gen_ai.choice事件會保留客服人員回應。
{
"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
-
gen_ai.tool.message 事件會保留工具引數，而gen_ai.choice事件會保留工具結果。
{
"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"
}
}
]
}
