View a markdown version of this page

为评估设置 Vercel AI SDK 遥测功能 AgentCore - Amazon Bedrock AgentCore
TypeScript 代理支持
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

为评估设置 Vercel AI SDK 遥测功能 AgentCore

本页介绍如何检测 Vercel AI SDK 代理、如何识别跨度以及如何提取评估字段。Vercel AI SDK 是一个 TypeScript-only 框架，因此此页面上的所有支持都适用于 TypeScript 代理。

注意

AgentCore 评估仅支持适用于 TypeScript 代理的 Vercel AI SDK。目前不支持 Python。

主题

TypeScript 代理支持

Vercel AI SDK 代理在作用域名称下生成跨度。@aws/aws-distro-opentelemetry-instrumentation-vercel-ai

为您的代理人提供仪器

使用 D Amazon istro for OpenTelemetry (ADOT) 为 Vercel AI SDK 代理安装工具。将 Amazon 发行版节点自动仪表包 (@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 生成式人工智能语义约定：它对跨度进行分类，gen_ai.operation.name并按属性进行对话。gen_ai.*

注意

仪器仪表是设置可观测性的一个步骤。要导出遥测数据进行评估，请在设置可观测性中完成完整设置。

如何识别跨度

Vercel AI 仪器在每个跨度上设置gen_ai.operation.name属性。评估服务使用此属性对跨度进行分类：

跨度类型 识别属性

调用代理

gen_ai.operation.name = invoke_agent

执行工具

gen_ai.operation.name = execute_tool

推理

gen_ai.operation.name = chat

如何提取评估字段

Vercel AI SDK 将消息序列化为两种形状， AgentCore 评估会同时显示两种形状：

  • 调用代理和推理跨度的输入上的对象字典形状，其中gen_ai.input.messages是一个带有system字段（系统提示符）和messages数组（例如，）的 JSON 对象。{"system": "…​", "messages": [{"role": "user", "content": "…​"}]}

  • 输出上的部分列表形状，其中每条消息都带有键入的内容块parts数组（例如，[{"role": "assistant", "parts": [{"type": "text", "content": "…​"}]}]）。

AgentCore 评估会从两种形状中提取文本：用户提示来自输入的最后一条用户消息，系统提示来自system字段，代理响应来自输出的文本部分。

Vercel AI 仪器使用统一的遥测技术，因此对话内容作为属性保持在跨度内：

  • 用户提示和代理响应：从gen_ai.input.messages调用代理跨度开始。gen_ai.output.messages

  • 系统提示：来自中的对象system字典字段。gen_ai.input.messages

  • 工具调用：执行工具跨度上的工具名称gen_ai.tool.call.arguments以及来自和gen_ai.tool.call.result的参数和结果。gen_ai.tool.name

有关更多信息，请参阅来自 TypeScript 代理的跨度示例。

来自代理的示例跨度 TypeScript

通过统一的遥测，对话内容将保留在 span 属性上，不会生成单独的事件记录。以下示例来自使用亚马逊 Bedrock 模型部署在亚马逊 Bedrock AgentCore Runtime 上的 TypeScript Vercel AI SDK 旅行计划代理。

注意

这些示例并不完整。它们显示来自真实代理交互的代表性数据，为了便于阅读，省略了一些字段并截断了长值。

例
Invoke agent span

gen_ai.operation.name属性 (invoke_agent) 将其标识为调用代理跨度。该gen_ai.input.messages属性以 object-dict 形状保存系统提示和对话，并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（对象字典形状）和gen_ai.output.messages（零件列表形状）。

{
  "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"
  }
}