Integração com o Vercel AI SDK

AI Gateway

Encaminhe suas chamadas de LLM pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: execute sempre o melhor modelo pelo menor custo para o seu caso de uso.

Observabilidade

Instrumente seu código com OpenTelemetry para capturar traces, logs e métricas de cada chamada de LLM, etapa de agente e uso de ferramenta.

AI Gateway

Visão geral

O Vercel AI SDK oferece kits de ferramentas em TypeScript e Python para criar aplicações com IA, com suporte a streaming, ferramentas e vários modelos. O SDK TypeScript também pode se conectar ao AI Gateway do Toqan Router por meio do @ai-sdk/openai-compatible, dando acesso a mais de 500 modelos com a configuração de um único provider.

Principais benefícios

O AI Gateway do Toqan Router aprimora suas aplicações Vercel AI com:

Observabilidade completa

Acompanhe cada geração, stream e saída estruturada com traces detalhados

Confiabilidade integrada

Fallbacks automáticos, novas tentativas e balanceamento de carga para resiliência em produção

Otimização de custos

Rastreamento de custos em tempo real e gestão de gastos em todas as suas operações de IA

Acesso a vários provedores

Acesse mais de 500 LLMs e mais de 30 provedores por meio de uma única integração unificada

Pré-requisitos

Antes de integrar o Vercel AI ao Toqan Router, verifique se você tem:

Uma conta no Toqan Router e uma chave de API
Node.js 18 ou superior

Para configurar sua chave de API, consulte Chaves de API e endpoints.

Instalação

npm install @ai-sdk/openai-compatible ai

Configuração

Configure o provider do Toqan Router com sua chave de API:

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

const toqan = createOpenAICompatible({
  name: "toqan",
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

base_url: https://router.toqan.ai/eu/v3/router

Geração de texto

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const toqan = createOpenAICompatible({
  name: "toqan",
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const { text } = await generateText({
  model: toqan("openai/gpt-5.6-sol"),
  prompt: "Write a haiku about programming",
});

console.log(text);

Respostas em streaming

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { streamText } from "ai";

const toqan = createOpenAICompatible({
  name: "toqan",
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const { textStream } = await streamText({
  model: toqan("openai/gpt-5.6-sol"),
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain quantum computing in two sentences." },
  ],
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

Saída estruturada

Use um system prompt em JSON e faça o parse da resposta:

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const toqan = createOpenAICompatible({
  name: "toqan",
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const { text } = await generateText({
  model: toqan("openai/gpt-5.6-sol"),
  messages: [
    {
      role: "system",
      content: "You are a data assistant. Always respond with valid JSON only, no markdown.",
    },
    {
      role: "user",
      content: "Generate information about France with fields: name, capital, population, languages.",
    },
  ],
});

const country = JSON.parse(text);
console.log(country);

Seleção de modelo

Com o Toqan Router, você pode usar qualquer modelo compatível de mais de 30 provedores:

TypeScript

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const toqan = createOpenAICompatible({
  name: "toqan",
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

// Use Claude
const claudeResult = await generateText({
  model: toqan("anthropic/claude-sonnet-5"),
  prompt: "What is the largest planet?",
});

// Use Gemini
const geminiResult = await generateText({
  model: toqan("google/gemini-2.5-flash"),
  prompt: "What is the largest planet?",
});

// Use Groq
const groqResult = await generateText({
  model: toqan("groq/qwen/qwen3.8-27b"),
  prompt: "What is the largest planet?",
});

Esforço de raciocínio com a Responses API

Ao chamar o endpoint Responses do AI Gateway por meio do @ai-sdk/openai, o SDK só envia reasoning se reconhecer o ID do modelo como um modelo de raciocínio da OpenAI. Um prefixo provider/, como em openai/gpt-5.6-sol, não passa nessa verificação; assim, reasoningEffort é descartado sem erro e o modelo é executado com seu esforço padrão. Defina forceReasoning: true (@ai-sdk/openai 3.x e posteriores) ou passe o ID do modelo sem prefixo. O AI Gateway encaminha um ID sem prefixo para a oferta do próprio desenvolvedor do modelo, então gpt-5.6-sol é encaminhado como openai/gpt-5.6-sol. No @ai-sdk/openai 2.x (AI SDK v5), apenas o ID sem prefixo funciona.

TypeScript

import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const oai = createOpenAI({
  baseURL: "https://router.toqan.ai/eu/v3/router",
  apiKey: process.env.TOQAN_API_KEY,
});

const { text } = await generateText({
  model: oai.responses("openai/gpt-5.6-sol"),
  prompt: "What is 2 + 2?",
  providerOptions: {
    openai: { reasoningEffort: "low", forceReasoning: true },
  },
});

Observabilidade

Primeiros passos

As duas implementações do Vercel AI SDK oferecem suporte ao OpenTelemetry, capturando execuções de agentes, chamadas de modelos, execuções de ferramentas, uso de tokens e erros. Exporte esses traces para o Toqan Router apontando um exportador OTLP padrão do OpenTelemetry para o coletor do Toqan Router: no SDK Python, pelo adaptador OpenTelemetry experimental_telemetry, e no SDK TypeScript, pelo pacote @ai-sdk/otel.

O AI SDK para TypeScript v7 moveu a coleta do OpenTelemetry do pacote ai para o pacote separado @ai-sdk/otel. Os spans só são emitidos depois que uma integração de telemetria é registrada com registerTelemetry. Definir apenas experimental_telemetry: { isEnabled: true } não emite nada na v7, então os traces nunca chegam ao Toqan Router. Consulte TypeScript AI SDK para a configuração da v7.

No momento, a Vercel classifica a telemetria em Python como experimental. A API e os atributos de span emitidos podem mudar entre versões.

Pré-requisitos

Antes de começar, verifique se você tem:

Uma conta no Toqan Router e uma chave de API.
Vercel AI SDK para TypeScript v7+, ou da v3.1 à v6 para a configuração legada. Vercel AI SDK para Python 0.4+.
Node.js 18+ (ou Bun 1.3.5+) para TypeScript, ou Python 3.12+ para Python.
Chaves de API dos seus provedores de LLM (OpenAI, Anthropic etc.).

Instale as dependências

Python
TypeScript

pip install "ai[otel,anthropic]" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

O extra otel adiciona o adaptador OpenTelemetry da Vercel. Substitua anthropic pelo extra do provedor que a aplicação usa, como openai.

# Core Vercel AI SDK with latest version
npm install ai@latest

# Telemetry collection (v7+; omit on v6 and earlier)
npm install @ai-sdk/otel

# OpenTelemetry packages
npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
npm install @opentelemetry/instrumentation @opentelemetry/resources
npm install @opentelemetry/semantic-conventions

# Next.js OpenTelemetry wiring (skip for standalone Node.js)
npm install @vercel/otel

# Provider SDKs (choose what you need)
npm install @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google

# Optional: For React applications
npm install @ai-sdk/react

Configure o ambiente de telemetria do TypeScript

Configure suas variáveis de ambiente para se conectar ao coletor OpenTelemetry do Toqan Router: Unix/Linux/macOS:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <TOQAN_API_KEY>"
export OTEL_RESOURCE_ATTRIBUTES="service.name=vercel-ai-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Windows (PowerShell):

$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer <TOQAN_API_KEY>"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=vercel-ai-app,service.version=1.0.0"
$env:OPENAI_API_KEY = "<YOUR_OPENAI_API_KEY>"

Usando um arquivo .env:

OTEL_EXPORTER_OTLP_ENDPOINT=https://router.toqan.ai/eu/v2/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <TOQAN_API_KEY>
OTEL_RESOURCE_ATTRIBUTES=service.name=vercel-ai-app,service.version=1.0.0
OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>

Integrações

Python AI SDK

O SDK Python mapeia sua telemetria para o OpenTelemetry por meio de um OtelAdapter. Configure um TracerProvider padrão do OpenTelemetry que exporte para o coletor do Toqan Router e registre o adaptador uma única vez na inicialização:

Python

import asyncio
import os

import ai
from ai.experimental_telemetry import register
from ai.experimental_telemetry.otel import OtelAdapter
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider(resource=Resource.create({"service.name": "weather-agent"}))
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://router.toqan.ai/eu/v2/otel/v1/traces",
            headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
        )
    )
)

register(OtelAdapter(tracer_provider=provider, capture_content=True))


@ai.tool
async def get_weather(city: str) -> str:
    """Get the current weather."""
    return f"72°F and sunny in {city}"


async def main() -> None:
    agent = ai.Agent(tools=[get_weather])
    model = ai.get_model("anthropic:claude-sonnet-5")

    async with agent.run(
        model,
        [ai.user_message("Weather in SF?")],
    ) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="")


try:
    asyncio.run(main())
finally:
    provider.force_flush()

register() instala o adaptador globalmente, de modo que toda execução de agente, chamada de modelo e execução de ferramenta posterior seja rastreada. capture_content=True inclui o conteúdo das mensagens nos spans. Chame provider.force_flush() antes que um script de curta duração termine, para que os spans em buffer sejam enviados. IDs de modelo no formato provider:model chamam o provedor diretamente usando a chave de API dele, como ANTHROPIC_API_KEY. IDs no formato provider/model são encaminhados pelo Vercel AI Gateway e exigem AI_GATEWAY_API_KEY.

TypeScript AI SDK

A configuração de telemetria varia conforme a versão principal. Na v7 e posteriores, a coleta do OpenTelemetry fica no pacote @ai-sdk/otel e é registrada uma única vez na inicialização. Na v6 e anteriores, ela é ativada por chamada por meio de experimental_telemetry.

Na v7, experimental_telemetry sozinho não emite spans. isEnabled controla uma integração registrada em vez de instalar uma; portanto, sem registerTelemetry não há nada a controlar e a chamada não produz nenhuma telemetria.

Os exemplos desta seção chamam diretamente o provider openai do @ai-sdk/openai. Isso envia as solicitações para a OpenAI sem passar pelo AI Gateway. Para encaminhar pelo Toqan Router, substitua openai pelo provider do @ai-sdk/openai-compatible, como mostrado na seção Geração de texto acima.

Registre o exportador OTLP e, em seguida, registre a integração de telemetria do AI SDK uma única vez na inicialização. Esta é a configuração para Next.js, em que o framework chama register() a partir do seu hook de instrumentação. Para Node.js standalone, conecte o exportador com NodeSDK, como mostrado em Captura de agentes e ferramentas.

// instrumentation.ts
import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel';
import { trace } from '@opentelemetry/api';
import { registerTelemetry } from 'ai';
import { OpenTelemetry } from '@ai-sdk/otel';

export function register() {
  registerOTel({
    serviceName: 'your-project-name',
    traceExporter: new OTLPHttpJsonTraceExporter({
      url: 'https://router.toqan.ai/eu/v2/otel/v1/traces',
      headers: {
        'Authorization': `Bearer ${process.env.TOQAN_API_KEY}`,
      },
    }),
  });

  registerTelemetry(new OpenTelemetry({ tracer: trace.getTracer('ai') }));
}

Passe tracer: trace.getTracer('ai'). Caso contrário, o @ai-sdk/otel nomeia seu tracer como gen_ai, que é o namespace genérico do OpenTelemetry, e não um marcador do AI SDK. O Toqan Router identifica o framework a partir desse escopo de instrumentação; sem ele, os traces são atribuídos ao OpenTelemetry genérico, e os agentes e ferramentas criados não são vinculados às suas execuções, tokens e custos.

O registro é global e do tipo opt-out: depois dele, toda chamada do AI SDK emite spans, sem necessidade de flag por chamada.

// index.ts
import './instrumentation.js';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

const result = await generateText({
  model: openai('gpt-5.5'),
  prompt: 'Write a short story about a robot',
});

As opções por chamada continuam valendo por meio de experimental_telemetry (ou do alias telemetry). Defina isEnabled: false para suprimir uma única chamada, recordInputs ou recordOutputs como false para manter prompts ou respostas fora dos spans e functionId para nomear a operação. functionId se torna gen_ai.agent.name no span invoke_agent, que é o que o Toqan Router registra como agente.

const result = await generateText({
  model: openai('gpt-5.5'),
  prompt: 'Explain quantum computing',
  experimental_telemetry: {
    functionId: 'quantum-explanation',
    recordInputs: false,
    recordOutputs: false,
  },
});

OpenTelemetry emite as convenções semânticas GenAI do OpenTelemetry (atributos gen_ai.*). O @ai-sdk/otel também exporta LegacyOpenTelemetry, que emite os atributos ai.* da v6. O Toqan Router ingere ambos. Para ver todas as opções de integração, consulte a documentação de telemetria do AI SDK. Ative a telemetria por chamada por meio da opção experimental_telemetry:

// instrumentation.js
import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel';

export function register() {
  registerOTel({
    serviceName: 'your-project-name',
    traceExporter: new OTLPHttpJsonTraceExporter({
      url: 'https://router.toqan.ai/eu/v2/otel/v1/traces',
      headers: {
        'Authorization': `Bearer ${process.env.TOQAN_API_KEY}`,
      },
    }),
  });
}

// index.js
import './instrumentation.js'
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

// Simple usage with telemetry enabled
const result = await generateText({
  model: openai("gpt-5.5"),
  prompt: "Write a short story about a robot",
  experimental_telemetry: {
    isEnabled: true,
  },
});

// Advanced configuration with custom metadata
const resultWithMetadata = await generateText({
  model: openai("gpt-5.5"),
  prompt: "Explain quantum computing",
  experimental_telemetry: {
    isEnabled: true,
    functionId: "quantum-explanation",
    metadata: {
      userId: "user-123",
      requestId: "req-456",
      environment: "production",
    },
  },
});

// Control what data is recorded
const userPrompt = "What is the meaning of life, the universe, and everything?";
const resultWithPrivacy = await generateText({
  model: openai("gpt-5.5"),
  prompt: userPrompt,
  experimental_telemetry: {
    isEnabled: true,
    recordInputs: false, // Don't record prompts
    recordOutputs: false, // Don't record responses
  },
});

Aqui, o principal para ativar a telemetria é incluir o seguinte payload ao gerar texto. Isso pode ser usado em todos os casos.

  experimental_telemetry: {
    isEnabled: true,
    recordInputs: false, // Don't record prompts
    recordOutputs: false, // Don't record responses
  },

Captura de agentes e ferramentas

Agentes, ferramentas e modelos são derivados dos spans e exibidos em Agent Graphs.

Instalação

npm install ai @ai-sdk/otel @ai-sdk/openai \
               @opentelemetry/api \
               @opentelemetry/sdk-node \
               @opentelemetry/exporter-trace-otlp-http

bun add ai @ai-sdk/otel @ai-sdk/openai \
           @opentelemetry/api \
           @opentelemetry/sdk-node \
           @opentelemetry/exporter-trace-otlp-http

Configuração

TypeScript

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
import { trace } from "@opentelemetry/api";
import { registerTelemetry } from "ai";
import { OpenTelemetry } from "@ai-sdk/otel";

const exporter = new OTLPTraceExporter({
  url: "https://router.toqan.ai/eu/v2/otel/v1/traces",
  headers: {
    Authorization: `Bearer ${process.env.TOQAN_API_KEY}`,
  },
});

const sdk = new NodeSDK({
  spanProcessor: new BatchSpanProcessor(exporter),
  serviceName: "my-ai-app",
});

sdk.start();
registerTelemetry(new OpenTelemetry({ tracer: trace.getTracer("ai") }));

registerTelemetry é obrigatório no AI SDK v7 e posteriores. Na v6 e anteriores, omita-o e passe experimental_telemetry: { isEnabled: true } em cada chamada.

Detecção de agentes

O exemplo abaixo chama diretamente o provider openai do @ai-sdk/openai, sem passar pelo AI Gateway. Substitua openai pelo provider do @ai-sdk/openai-compatible para encaminhar pelo Toqan Router.

O Vercel AI SDK não tem uma forma integrada de marcar um span como agente. Para capturar agentes, use instrumentação manual do OpenTelemetry com tracer.startActiveSpan(). O nome do span (por exemplo, "translator-agent") se torna o nome do agente. Essa abordagem captura ferramentas e modelos junto com o span do agente.

O exemplo abaixo é para o AI SDK v7. Na v6 e anteriores, remova registerTelemetry e adicione isEnabled: true ao bloco experimental_telemetry.

Captura: agent/translator-agent, tool/translate, model/gpt-5.6-sol

TypeScript

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
import { openai } from "@ai-sdk/openai";
import { context, trace } from "@opentelemetry/api";
import { generateText, jsonSchema, registerTelemetry, stepCountIs, tool } from "ai";
import { OpenTelemetry } from "@ai-sdk/otel";

const exporter = new OTLPTraceExporter({
  url: "https://router.toqan.ai/eu/v2/otel/v1/traces",
  headers: { Authorization: `Bearer ${process.env.TOQAN_API_KEY}` },
});

const sdk = new NodeSDK({
  spanProcessor: new BatchSpanProcessor(exporter),
  serviceName: "my-ai-app",
});

sdk.start();
registerTelemetry(new OpenTelemetry({ tracer: trace.getTracer("ai") }));

const translateTool = tool({
  description: "Translate text to a target language",
  inputSchema: jsonSchema<{ text: string; target_language: string }>({
    type: "object",
    properties: {
      text: { type: "string", description: "Text to translate" },
      target_language: { type: "string", description: "Target language" },
    },
    required: ["text", "target_language"],
  }),
  execute: async ({ text, target_language }) => {
    const translations: Record<string, Record<string, string>> = {
      spanish: { "Hello, how are you?": "¡Hola, ¿cómo estás?" },
      french: { "Hello, how are you?": "Bonjour, comment allez-vous?" },
      japanese: { "Hello, how are you?": "こんにちは、お元気ですか？" },
    };
    return (
      translations[target_language.toLowerCase()]?.[text] ||
      `[${target_language}] ${text}`
    );
  },
});

const tracer = trace.getTracer("ai-sdk-app");

await tracer.startActiveSpan("translator-agent", async (parentSpan) => {
  parentSpan.setAttribute("input", 'Translate "Hello, how are you?" to Spanish');

  await context.with(
    trace.setSpan(context.active(), parentSpan),
    async () => {
      try {
        const { text } = await generateText({
          model: openai("gpt-5.6-sol"),
          system: "You are a translator agent that helps users translate text to different languages.",
          prompt: 'Translate "Hello, how are you?" to Spanish',
          tools: { translate: translateTool },
          stopWhen: stepCountIs(3),
          experimental_telemetry: { functionId: "translator_agent" },
        });

        console.log(text);
        parentSpan.setAttribute("output", text);
      } finally {
        parentSpan.end();
      }
    },
  );
});

await sdk.shutdown();

Visão geral

Instrumente seu app

Explorar

Monitorar

Exportar

Revisar

Privacidade e segurança de dados

Integrações com frameworks

AI Gateway

Observabilidade

AI Gateway

Visão geral

Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a vários provedores

Pré-requisitos

Instalação

Configuração

Geração de texto

Respostas em streaming

Saída estruturada

Seleção de modelo

Esforço de raciocínio com a Responses API

Observabilidade

Primeiros passos

Pré-requisitos

Instale as dependências

Configure o ambiente de telemetria do TypeScript

Integrações

Python AI SDK

TypeScript AI SDK

Captura de agentes e ferramentas

Instalação

Configuração

Detecção de agentes

AI Gateway

Observabilidade

​AI Gateway

​Visão geral

​Principais benefícios

Observabilidade completa

Confiabilidade integrada

Otimização de custos

Acesso a vários provedores

​Pré-requisitos

​Instalação

​Configuração

​Geração de texto

​Respostas em streaming

​Saída estruturada

​Seleção de modelo

​Esforço de raciocínio com a Responses API

​Observabilidade

​Primeiros passos

​Pré-requisitos

​Instale as dependências

​Configure o ambiente de telemetria do TypeScript

​Integrações

​Python AI SDK

​TypeScript AI SDK

​Captura de agentes e ferramentas

​Instalação

​Configuração

​Detecção de agentes

AI Gateway

Visão geral

Principais benefícios

Pré-requisitos

Instalação

Configuração

Geração de texto

Respostas em streaming

Saída estruturada

Seleção de modelo

Esforço de raciocínio com a Responses API

Observabilidade

Primeiros passos

Pré-requisitos

Instale as dependências

Configure o ambiente de telemetria do TypeScript

Integrações

Python AI SDK

TypeScript AI SDK

Captura de agentes e ferramentas

Instalação

Configuração

Detecção de agentes