本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 为评估设置 Vercel AI SDK 遥测功能 AgentCore
本页介绍如何检测 [ Vercel AI SDK ](https://sdk.vercel.ai/) 代理、如何识别跨度以及如何提取评估字段。Vercel AI SDK 是一个 TypeScript-only 框架，因此此页面上的所有支持都适用于 TypeScript 代理。
**注意**
AgentCore 评估仅支持适用于 TypeScript 代理的 Vercel AI SDK。目前不支持 Python。
**主题**
+ [TypeScript 代理支持 ](#vercel-ai-typescript)
+ [为您的代理人提供仪器 ](#vercel-ai-instrument)
+ [如何识别跨度 ](#vercel-ai-span-identification)
+ [如何提取评估字段 ](#vercel-ai-extraction)
+ [来自代理的示例跨度 TypeScript ](#vercel-ai-examples-typescript)
## 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.*`
**注意**
仪器仪表是设置可观测性的一个步骤。要导出遥测数据进行评估，请在设置可观[测性中](supported-frameworks-telemetry.md#supported-frameworks-setup)完成完整设置。
### 如何识别跨度
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 代理[的跨度](#vercel-ai-examples-typescript)示例。
### 来自代理的示例跨度 TypeScript
通过统一的遥测，对话内容将保留在 span 属性上，不会生成单独的事件记录。以下示例来自使用亚马逊 Bedrock 模型部署在亚马逊 Bedrock AgentCore Runtime 上的 TypeScript Vercel AI SDK 旅行计划代理。
**注意**
这些示例并不完整。它们显示来自真实代理交互的代表性数据，为了便于阅读，省略了一些字段并截断了长值。
**Example**
`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"
}
}
```
`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"
}
}
```
`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"
}
}
```