View a markdown version of this page

Configura la telemetria Vercel AI SDK per le valutazioni AgentCore - Fondamento Amazon AgentCore
TypeScript supporto per gli agenti

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Configura la telemetria Vercel AI SDK per le valutazioni AgentCore

Questa pagina spiega come strumentare un agente Vercel AI SDK, come vengono identificati gli intervalli e come vengono estratti i campi di valutazione. Vercel AI SDK è un TypeScript-only framework, quindi tutto il supporto in questa pagina si applica agli agenti. TypeScript

Nota

AgentCore Evaluations supporta l'SDK Vercel AI solo per agenti. TypeScript Python non è supportato in questo momento.

Argomenti

TypeScript supporto per gli agenti

Un agente Vercel AI SDK produce intervalli con il nome dell'ambito. @aws/aws-distro-opentelemetry-instrumentation-vercel-ai

Strumenta il tuo agente

Strumenta un agente Vercel AI SDK con AWS Distro for OpenTelemetry (ADOT). Aggiungi il pacchetto di autostrumentazione AWS Distro Node () alle tue dipendenze. @aws/aws-distro-opentelemetry-node-autoinstrumentation Include la strumentazione Vercel AI integrata, che si attiva all'avvio ed emette il nome dell'ambito. @aws/aws-distro-opentelemetry-instrumentation-vercel-ai

package.json:

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

La strumentazione segue le convenzioni semantiche dell' OpenTelemetry IA generativa: classifica gli intervalli e raggruppa la conversazione in attributi. gen_ai.operation.name gen_ai.*

Nota

La strumentazione è un passo verso l'impostazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità. Imposta l'osservabilità

Come vengono identificati gli intervalli

La strumentazione Vercel AI imposta l'gen_ai.operation.nameattributo su ogni intervallo. Il servizio di valutazione utilizza questo attributo per classificare gli intervalli:

Tipo di intervallo Attributo identificativo

Invoca l'agente

gen_ai.operation.name = invoke_agent

Strumento di esecuzione

gen_ai.operation.name = execute_tool

Inferenza

gen_ai.operation.name = chat

Come vengono estratti i campi di valutazione

Vercel AI SDK serializza i messaggi in due forme e Evaluations legge entrambe: AgentCore

  • Una forma object-dict sull'input dell'agente invoke e dell'inferenza si estende, in cui gen_ai.input.messages è presente un oggetto JSON con un system campo (il prompt di sistema) e un array (ad esempio,). messages {"system": "…​", "messages": [{"role": "user", "content": "…​"}]}

  • Una forma di elenco delle parti sull'output, in cui ogni messaggio contiene una parts serie di blocchi di contenuto digitati (ad esempio,). [{"role": "assistant", "parts": [{"type": "text", "content": "…​"}]}]

AgentCore Le valutazioni estraggono il testo da entrambe le forme: il prompt dell'utente dall'ultimo messaggio utente inserito nell'input, il prompt di sistema dal system campo e la risposta dell'agente dalle parti di testo dell'output.

La strumentazione Vercel AI utilizza la telemetria unificata, quindi il contenuto della conversazione rimane nell'intervallo come attributi:

  • Richiesta dell'utente e risposta dell'agente: da e verso l'intervallo dell'agente invoke. gen_ai.input.messages gen_ai.output.messages

  • Prompt di sistema: dal system campo dell'object-dict in. gen_ai.input.messages

  • Chiamata allo strumento: il nome dello strumento dagen_ai.tool.name, gli argomenti e il risultato da gen_ai.tool.call.arguments e gen_ai.tool.call.result nell'intervallo di esecuzione dello strumento.

Per ulteriori informazioni, consulta Example spans from a TypeScript agent.

Esempio tratto da un agente TypeScript

Con la telemetria unificata, il contenuto della conversazione rimane negli attributi span e non viene prodotto alcun record di evento separato. Gli esempi seguenti sono tratti da un agente di pianificazione dei viaggi TypeScript Vercel AI SDK distribuito su Amazon Bedrock Runtime, utilizzando un modello Amazon Bedrock. AgentCore

Nota

Questi esempi non sono intervalli completi. Mostrano dati rappresentativi di un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità.

Esempio
Invoke agent span

L'gen_ai.operation.nameattributo (invoke_agent) lo identifica come un invoke agent span. L'gen_ai.input.messagesattributo contiene il prompt e la conversazione del sistema nella forma object-dict e gen_ai.output.messages contiene la risposta dell'agente nella forma parts-list.

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

L'gen_ai.operation.nameattributo (execute_tool) lo identifica come un intervallo di esecuzione dello strumento; contiene il nome dello strumento. gen_ai.tool.name L'gen_ai.tool.call.argumentsattributo contiene gli argomenti dello strumento e l'gen_ai.tool.call.resultattributo contiene il risultato dello strumento.

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

L'gen_ai.operation.nameattributo (chat) lo identifica come intervallo di inferenza. Contiene i metadati del modello e, all'internogen_ai.tool.definitions, l'elenco degli strumenti disponibili per l'agente. I messaggi di conversazione per la chiamata al modello sono in gen_ai.input.messages (object-dict shape) e gen_ai.output.messages (parts-list shape).

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