檢測您的代理程式如何識別跨度如何擷取評估欄位範例跨越事件記錄沒有事件記錄的範例範圍

Claude 代理程式開發套件

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

主題

檢測您的代理程式
如何識別跨度
如何擷取評估欄位
- 從事件記錄
- 從跨度屬性
範例跨越事件記錄
沒有事件記錄的範例範圍

檢測您的代理程式

您可以使用 OpenInference 檢測程式庫 () 檢測 Claude Agent SDK 代理程式openinference-instrumentation-claude-agent-sdk。此程式庫會在 Amazon Bedrock AgentCore Evaluations openinference.instrumentation.claude_agent_sdk讀取的範圍名稱下發出遙測。

當您的代理程式使用 AWS Distro for OpenTelemetry (ADOT) 執行時，例如在 Amazon Bedrock AgentCore 執行期，您不需要新增明確的檢測程式碼。將檢測程式庫新增至專案的相依性已足夠。ADOT 在啟動時發現它並自動啟用它。

將檢測程式庫新增至您的相依性。

注意

使用版本 0.1.3 或更新版本。這是使用評估服務測試的最早版本。

requirements.txt:


openinference-instrumentation-claude-agent-sdk>=0.1.3

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-claude-agent-sdk>=0.1.3",
]

注意

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

如何識別跨度

Claude Agent SDK 使用 OpenInference 慣例進行檢測，因此 AgentCore Evaluations 會使用 openinference.span.kind 屬性對範圍進行分類。

跨度類型	識別屬性
叫用代理程式	`openinference.span.kind` = `AGENT`
執行工具	`openinference.span.kind` = `TOOL`

Claude Agent SDK 只會發出 AGENT 和 TOOL 跨度；不會發出單獨的推論 (LLM) 跨度。模型中繼資料（模型名稱、字符用量） AGENT 和代理程式回應會在跨度本身上進行。

如何擷取評估欄位

Claude Agent SDK 會產生簡潔的純文字代理程式輸入和輸出，因此使用者提示和代理程式回應不需要特殊剖析。不過，工具結果會以格式的 Anthropic 內容區塊的形式送達[{"type": "text", "text": "…"}]。AgentCore Evaluations 會取消包裝這些區塊，並串連其文字。

此內容的位置取決於收集遙測的方式。在這兩種情況下，識別屬性 (openinference.span.kind) 位於跨度。如需詳細資訊，請參閱跨度、事件記錄和遙測訊號。

從事件記錄

分割遙測時，AgentCore Evaluations 會從與每個範圍相關的事件記錄中讀取內容：

使用者提示和客服人員回應：在 body.input和中，從調用客服人員的事件記錄body.output。
工具呼叫：tool.name來自屬性的工具名稱，以及執行工具範圍tool.id上來自的工具呼叫 ID。工具引數和結果來自 body.input和中的跨度事件記錄body.output。AgentCore Evaluations 會取消包裝工具結果中的 Anthropic 內容區塊。

如需範例，請參閱範例跨越事件記錄。

從跨度屬性

未分割遙測時，相同的內容會保留在跨度上做為屬性：

使用者提示和客服人員回應：調用客服人員範圍output.value上的 input.value和。
工具呼叫：執行工具範圍上來自的工具名稱tool.name、來自的工具呼叫 IDinput.value、來自的tool.id引數output.value，以及來自的結果。AgentCore Evaluations 會取消包裝工具結果中的 Anthropic 內容區塊。

如需範例，請參閱沒有事件記錄的範例跨度。

範例跨越事件記錄

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

注意

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

範例

Invoke agent span

openinference.span.kind 屬性 (AGENT) 將此識別為調用代理程式範圍。範圍會攜帶模型中繼資料；對話內容會存在於相關事件記錄中。


{
  "traceId": "6a292d74406894815807e2751e61dd49",
  "spanId": "a63aab3320ed8718",
  "name": "ClaudeAgentSDK.ClaudeSDKClient.receive_response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.5"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "llm.system": "anthropic",
    "llm.model_name": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "input.mime_type": "text/plain",
    "output.mime_type": "text/plain",
    "session.id": "sea-nyc-trip-2-turns-claude-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "a63aab3320ed8718",
  "traceId": "6a292d74406894815807e2751e61dd49",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "Hey, how can you help me" }
      ]
    },
    "output": {
      "messages": [
        { "role": "assistant", "content": "Hello! I'm your travel planning assistant ..." }
      ]
    }
  }
}

Execute tool span

openinference.span.kind 屬性 (TOOL) 將此識別為執行工具範圍； tool.name會保留工具名稱和tool.id工具呼叫 ID。工具結果會以 Anthropic 內容區塊的形式存在於相關事件記錄中，AgentCore Evaluations 會取消包裝。


{
  "traceId": "6a292deb7450b3155895da4f38cb579a",
  "spanId": "909dcb4eb5f851ae",
  "name": "mcp__travel__search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.5"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "mcp__travel__search_flights",
    "tool.id": "toolu_bdrk_01KmJhCRuEJJo6fswHbjCgFp",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-claude-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "909dcb4eb5f851ae",
  "traceId": "6a292deb7450b3155895da4f38cb579a",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "[{\"type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]"
        }
      ]
    }
  }
}

沒有事件記錄的範例範圍

未分割遙測時，相同的內容會保留在跨度屬性上，而且不會產生單獨的事件記錄。下列範例來自 Claude Agent SDK 行程規劃代理程式。

注意

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

範例

Invoke agent span

input.value 屬性會保留使用者提示，而output.value屬性會保留客服人員回應，兩者都是純文字。


{
  "traceId": "561876bb17e9eaeb2f194ee515742b2f",
  "spanId": "3b6815f5b3909a51",
  "name": "ClaudeAgentSDK.ClaudeSDKClient.receive_response",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.3"
  },
  "attributes": {
    "openinference.span.kind": "AGENT",
    "llm.system": "anthropic",
    "llm.model_name": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "input.value": "Hey, how can you help me",
    "input.mime_type": "text/plain",
    "output.value": "Hi there! ... How can I help you plan your next adventure?",
    "output.mime_type": "text/plain",
    "session.id": "sea-nyc-trip-2-turns-claude-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

input.value 屬性會保留工具引數，而 output.value 屬性會將工具結果保留為 Anthropic 內容區塊，AgentCore Evaluations 會取消包裝。


{
  "traceId": "7bb7e59a30d03fc0b9da5bf009a3b429",
  "spanId": "d27b488965bbba99",
  "name": "mcp__travel__search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.claude_agent_sdk",
    "version": "0.1.3"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "mcp__travel__search_flights",
    "tool.id": "toolu_bdrk_019yE7Gne1rZKE3UnVPAWjLq",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.mime_type": "application/json",
    "output.value": "[{\"type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-claude-unified"
  },
  "status": {
    "code": "OK"
  }
}

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

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

文件慣用形式

Google ADK

內建評估器