# Strands 代理程式
<a name="supported-frameworks-strands"></a>

此頁面說明如何檢測 [Strands Agents ](https://strandsagents.com/latest/)代理程式、如何識別範圍，以及如何擷取評估欄位。

 **主題** 
+  [檢測您的代理程式](#strands-instrument) 
+  [如何識別跨度](#strands-span-identification) 
+  [如何擷取評估欄位](#strands-extraction) 
  +  [從事件記錄](#strands-extraction-event-records) 
  +  [從內嵌跨度事件](#strands-extraction-inline-events) 
+  [範例跨越事件記錄](#strands-examples-with) 
+  [沒有事件記錄的範例範圍](#strands-examples-without) 

## 檢測您的代理程式
<a name="strands-instrument"></a>

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

**注意**  
檢測是設定可觀測性的一個步驟。若要匯出遙測資料進行評估，請完成設定[可觀測性中的完整設定](supported-frameworks.md#supported-frameworks-setup)。

## 如何識別跨度
<a name="strands-span-identification"></a>

字串會在每個範圍上設定 `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`  | 

## 如何擷取評估欄位
<a name="strands-extraction"></a>

對話內容的位置取決於收集遙測的方式。當 ADOT 分割遙測時，內容會位於單獨的事件記錄中。未分割遙測時，內容會保留在跨度上做為內嵌事件。如需詳細資訊，請參閱[跨度、事件記錄和遙測訊號](supported-frameworks-telemetry.md)。在這兩種情況下，識別屬性 (`gen_ai.operation.name`) 位於跨度。

### 從事件記錄
<a name="strands-extraction-event-records"></a>

分割遙測時，服務會從與每個範圍相關的事件記錄中讀取內容：
+  **使用者提示**：從客服人員輸入訊息 (`input.messages`)，使用使用者角色的訊息內容。
+  **客服人員回應**：來自客服人員輸出訊息 (`output.messages`)，訊息內容與 助理角色。
+  **工具呼叫**：執行工具範圍上 `gen_ai.tool.name` 屬性的工具名稱。工具引數和結果來自該範圍的事件記錄 (`input` 和 `output`)。

如需範例，請參閱[範例跨越事件記錄](#strands-examples-with)。

### 從內嵌跨度事件
<a name="strands-extraction-inline-events"></a>

未分割遙測時，相同的內容會在內嵌跨度事件中傳送，而不是單獨的事件記錄：
+  **使用者提示**：來自 `gen_ai.user.message`事件的 `content` 屬性。
+  **客服人員回應**：來自 `gen_ai.choice`事件的 `message` 屬性。
+  **工具呼叫**：來自跨度上 `gen_ai.tool.name` 屬性的工具名稱。工具引數來自`gen_ai.tool.message`事件，而結果來自`gen_ai.choice`事件。

如需範例，請參閱[沒有事件記錄的範例跨度](#strands-examples-without)。

## 範例跨越事件記錄
<a name="strands-examples-with"></a>

分割遙測時，範圍會攜帶識別屬性，而內容會存在於相關事件記錄中。下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 Strands 行程規劃代理程式。

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

**Example**  
`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"
          }
        }
      ]
    }
  }
}
```
`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"
          }
        }
      ]
    }
  }
}
```

## 沒有事件記錄的範例範圍
<a name="strands-examples-without"></a>

未分割遙測時，相同的內容會在跨度的內嵌跨度事件中傳送，沒有單獨的事件記錄。下列範例來自 Strands 旅行規劃代理程式。

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

**Example**  
`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"
      }
    }
  ]
}
```
`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"
      }
    }
  ]
}
```