為 AgentCore 評估設定 Strands Agents 遙測

此頁面說明如何檢測 Strands Agents 代理程式、如何識別範圍，以及如何擷取評估欄位。

主題

Python 代理程式支援
TypeScript 代理程式支援

AgentCore Evaluations 支援使用 Python SDK 和 TypeScript SDK 建置的 Strands 代理程式。兩者會在不同的範圍名稱下產生相同的跨度類型、識別屬性和內容配置，因此評估服務會以相同的方式讀取它們。此頁面分別涵蓋每種語言：對於 Python，請參閱 Python 代理程式支援；對於 TypeScript，請參閱 TypeScript 代理程式支援。

Python 代理程式支援

Python Strands 代理程式會在範圍名稱下產生範圍strands.telemetry.tracer。

檢測您的代理程式

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`

如何擷取評估欄位

對話內容的位置取決於遙測交付模式。使用分割遙測時，內容會位於單獨的事件記錄中。使用統一遙測，內容會保留在跨度上，做為附加到其中的事件。如需詳細資訊，請參閱遙測設定和交付。識別屬性 (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 執行期上的 Python 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"
          }
        }
      ]
    }
  }
}

統一遙測中的範例範圍

使用統一遙測，相同的內容會在跨度的內嵌跨度事件中傳送，沒有單獨的事件記錄。下列範例來自 Python 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"
      }
    }
  ]
}

TypeScript 代理程式支援

TypeScript Strands 代理程式會在範圍名稱下產生範圍strands-agents。它會發出與 Python 代理程式相同的跨度類型和內容配置，因此評估服務會以相同的方式讀取。

檢測您的代理程式

TypeScript Strands Agents SDK (@strands-agents/sdk>= 1.5.0) 包含內建遙測，不需要額外的檢測程式庫。使用 AWS Distro for OpenTelemetry (ADOT) 部署在 Amazon Bedrock AgentCore 執行期時，執行期會自動插入session.id屬性並匯出範圍和事件記錄。TypeScript SDK 會在範圍名稱下產生範圍strands-agents。

注意

檢測是設定可觀測性的一個步驟。若要匯出遙測資料進行評估，請完成設定可觀測性中的完整設定。

如何識別跨度

跨度識別與 Python 代理程式相同。gen_ai.operation.name 屬性會分類每個跨度。如需值和範例跨度名稱，請參閱 Python 支援下的跨度識別方式。

如何擷取評估欄位

欄位擷取與 Python 代理程式相同。對話內容會在內嵌跨度事件 (gen_ai.user.message、 gen_ai.choice和 ) 中傳送gen_ai.tool.message。如需讀取每個欄位的位置，請參閱 Python 支援下的從內嵌跨度事件。

來自 TypeScript 代理程式的範例

下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 TypeScript Strands 行程規劃代理程式。

注意

這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。

範例

Invoke agent span

gen_ai.operation.name 屬性 (invoke_agent) 將此識別為調用客服人員範圍，並gen_ai.agent.tools列出客服人員可用的工具。gen_ai.user.message 事件會保留使用者提示，而gen_ai.choice事件會保留客服人員回應。


{
  "traceId": "6a6bc695459e41aa14a172bb41d3246d",
  "spanId": "c2c44e69bdab6ef1",
  "parentSpanId": "f18d96d107e793ba",
  "name": "invoke_agent Strands Agent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands-agents",
    "version": ""
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "Strands Agent",
    "gen_ai.system": "strands-agents",
    "gen_ai.request.model": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "events": [
    {
      "name": "gen_ai.user.message",
      "attributes": {
        "content": "[{\"text\": \"Hey, how can you help me\"}]"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "Hello! I'm your travel planning assistant, and I can help you with the following: ..."
      }
    }
  ]
}

Execute tool span

gen_ai.operation.name 屬性 (execute_tool) 將此識別為執行工具範圍； gen_ai.tool.name會保留工具名稱。gen_ai.tool.message 事件會保留工具引數，而gen_ai.choice事件會保留工具結果。


{
  "traceId": "6a6bc69e6eaa1e994481bef349f4c72e",
  "spanId": "4227ac5525f22dd2",
  "parentSpanId": "8a989e0dbb9dc22f",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands-agents",
    "version": ""
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ",
    "gen_ai.tool.status": "success",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "events": [
    {
      "name": "gen_ai.tool.message",
      "attributes": {
        "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
        "role": "tool",
        "id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
        "id": "tooluse_AoP0OTnq2YcOZDvY7ldSUQ"
      }
    }
  ]
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

支援的架構

LangGraph