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는 TypeScript 에이전트용 Vercel AI SDK만 지원합니다. 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.input.messages 및 gen_ai.output.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 (객체 예측 셰이프) 및 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"
  }
}