View a markdown version of this page

為 AgentCore 評估設定 Vercel AI SDK 遙測 - Amazon Bedrock AgentCore
TypeScript 代理程式支援

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

為 AgentCore 評估設定 Vercel AI SDK 遙測

此頁面說明如何檢測 Vercel AI SDK 代理程式、如何識別範圍，以及如何擷取評估欄位。Vercel AI SDK 是僅限 TypeScript 的架構，因此此頁面上的所有支援都適用於 TypeScript 代理程式。

注意

AgentCore Evaluations 僅支援 Vercel AI SDK for TypeScript 代理程式。目前不支援 Python。

主題

TypeScript 代理程式支援

Vercel AI SDK 代理程式會在範圍名稱 下產生範圍@aws/aws-distro-opentelemetry-instrumentation-vercel-ai。

檢測您的代理程式

使用 AWS Distro for OpenTelemetry (ADOT) 檢測 Vercel AI SDK 代理程式。將 AWS Distro Node 自動檢測套件 (@aws/aws-distro-opentelemetry-node-autoinstrumentation) 新增至您的相依性。它包含內建的 Vercel AI 檢測，會在啟動時啟用並發出範圍名稱 @aws/aws-distro-opentelemetry-instrumentation-vercel-ai。

package.json:

{
  "dependencies": {
    "@aws/aws-distro-opentelemetry-node-autoinstrumentation": "^0.12.0"
  }
}

檢測遵循 OpenTelemetry 生成式 AI 語意慣例：它將跨度分類為 ，gen_ai.operation.name並在gen_ai.*屬性中進行對話。

注意

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

如何識別跨度

Vercel AI 檢測會在每個範圍上設定 gen_ai.operation.name 屬性。評估服務使用此屬性來分類跨度：

跨度類型 識別屬性

叫用代理程式

gen_ai.operation.name = invoke_agent

執行工具

gen_ai.operation.name = execute_tool

Inference

gen_ai.operation.name = chat

如何擷取評估欄位

Vercel AI SDK 會以兩種形狀序列化訊息，而 AgentCore Evaluations 會讀取兩者：

  • 叫用代理程式輸入上的物件裁切形狀和推論範圍，其中 gen_ai.input.messages 是具有system欄位 （系統提示） 和messages陣列 （例如，) 的 JSON 物件{"system": "…​", "messages": [{"role": "user", "content": "…​"}]}。

  • 輸出上的部分清單形狀，其中每個訊息都攜帶parts一組類型內容區塊 （例如，[{"role": "assistant", "parts": [{"type": "text", "content": "…​"}]}])。

AgentCore Evaluations 會從兩種形狀中提取文字：來自輸入中最後一個使用者訊息的使用者提示、來自 system 欄位的系統提示，以及來自輸出文字部分的客服人員回應。

Vercel AI 檢測使用統一遙測，因此對話內容會保留在跨度上做為屬性：

  • 使用者提示和客服人員回應：調用客服人員範圍gen_ai.output.messages上的 gen_ai.input.messages和 。

  • 系統提示：來自 中 object-dict 的 system 欄位gen_ai.input.messages。

  • 工具呼叫：執行工具範圍gen_ai.tool.call.result上來自 的工具名稱gen_ai.tool.name，以及來自 和 的引數gen_ai.tool.call.arguments和結果。

如需詳細資訊，請參閱 TypeScript 代理程式的範例範圍。

來自 TypeScript 代理程式的範例

使用統一遙測，對話內容會保留在跨度屬性上，不會產生單獨的事件記錄。下列範例來自使用 Amazon Bedrock 模型部署在 Amazon Bedrock AgentCore 執行期上的 TypeScript Vercel AI SDK 行程規劃代理程式。

注意

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

範例
Invoke agent span

gen_ai.operation.name 屬性 (invoke_agent) 將此識別為調用代理程式範圍。gen_ai.input.messages 屬性會將系統提示和對話保留為物件方向，並將代理程式回應gen_ai.output.messages保留為部分清單形狀。

{
  "traceId": "6a6bd3b14c8d91ed1e70a3906b551618",
  "spanId": "fa0dce44446e3d24",
  "name": "invoke_agent",
  "kind": "INTERNAL",
  "scope": {
    "name": "@aws/aws-distro-opentelemetry-instrumentation-vercel-ai",
    "version": "0.12.0"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.provider.name": "aws.bedrock",
    "gen_ai.request.model": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "gen_ai.input.messages": "{\"system\": \"You are a travel planning assistant ...\", \"messages\": [{\"role\": \"user\", \"content\": \"Hey, how can you help me\"}]}",
    "gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"Hello! I'm your travel planning assistant ...\"}]}]",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}
Execute tool span

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

{
  "traceId": "6a6bd3b14c8d91ed1e70a3906b551618",
  "spanId": "b64c37adefae74f0",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "@aws/aws-distro-opentelemetry-instrumentation-vercel-ai",
    "version": "0.12.0"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "function",
    "gen_ai.tool.call.id": "toolu_bdrk_01LzXXJCfpfuS7Bpf7e1qLMg",
    "gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}
Inference span

gen_ai.operation.name 屬性 (chat) 將此識別為推論範圍。它攜帶模型中繼資料，並在 中gen_ai.tool.definitions攜帶可供代理程式使用的工具清單。模型呼叫的對話訊息為 gen_ai.input.messages(object-dict 形狀） 和 gen_ai.output.messages(parts-list 形狀）。

{
  "traceId": "6a6bd3b14c8d91ed1e70a3906b551618",
  "spanId": "1865614ca1b88dfb",
  "name": "chat us.anthropic.claude-sonnet-4-5-20250929-v1:0",
  "kind": "INTERNAL",
  "scope": {
    "name": "@aws/aws-distro-opentelemetry-instrumentation-vercel-ai",
    "version": "0.12.0"
  },
  "attributes": {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "aws.bedrock",
    "gen_ai.request.model": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "gen_ai.response.model": "us.anthropic.claude-sonnet-4-5-20250929-v1:0",
    "gen_ai.usage.input_tokens": 1258,
    "gen_ai.usage.output_tokens": 241,
    "gen_ai.input.messages": "{\"system\": \"You are a travel planning assistant ...\", \"messages\": [{\"role\": \"user\", \"content\": \"Hey, how can you help me\"}]}",
    "gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"Hello! I'm your travel planning assistant ...\"}]}]",
    "gen_ai.tool.definitions": "[{\"type\": \"function\", \"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", ...}]",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}