Pular para o conteúdo principal

AI Gateway

Roteie as chamadas de modelo dos agentes pelo AI Gateway alterando apenas a URL base. Sem dependência de fornecedor: rode sempre no melhor modelo, com o menor custo para a carga de trabalho.

Observabilidade

Exporte os traces e logs emitidos pelos Workers para o Toqan Router via OpenTelemetry, direto do runtime dos Workers.

AI Gateway

Visão geral

Os Cloudflare Agents rodam em Workers e Durable Objects e chamam modelos por meio do AI SDK. Apontar esse provedor para o AI Gateway do Toqan Router faz toda chamada de modelo que o utiliza passar pelo gateway, de modo que roteamento, fallbacks e rastreamento de custos se aplicam a essas chamadas. Chamadas que usam diretamente o binding do Workers AI continuam indo para a Cloudflare.

Principais benefícios

Conectar o Cloudflare Agents ao AI Gateway do Toqan Router adiciona:

Observabilidade completa

Acompanhe as chamadas de modelo e o uso de tokens com traces e analytics detalhados

Confiabilidade integrada

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

Otimização de custos

Rastreamento de custos em tempo real e gestão de gastos em cada operação de IA

Acesso a múltiplos 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 Cloudflare Agents ao Toqan Router, confirme que você tem:
  • Uma conta do Toqan Router e uma chave de API
  • Uma conta da Cloudflare com um Worker criado a partir do starter do Cloudflare Agents
  • wrangler instalado e autenticado

Instalação

Instale o Agents SDK e o AI SDK com o provedor compatível com OpenAI:
Armazene a chave de API do Toqan Router como um secret do Worker:

Configurar o gateway

Crie o provedor uma única vez e passe para ele a URL base do gateway. this.env contém o secret armazenado acima:
TypeScript
baseURL: https://router.toqan.ai/eu/v3/router

Exemplo básico de agente

Toda chamada de modelo em uma subclasse de Agent passa pelo gateway com esse provedor:
TypeScript
Para um agente de chat com streaming, o AIChatAgent do starter recebe o mesmo provedor em onChatMessage:
TypeScript

Seleção de modelo

Com o Toqan Router, use qualquer modelo suportado de mais de 30 provedores alterando o ID do modelo:
TypeScript
Consulte Modelos suportados para ver o catálogo.

Observabilidade

Primeiros passos

A Cloudflare exporta a telemetria dos Workers para qualquer destino compatível com OpenTelemetry, e o Toqan Router é um deles; assim, traces e logs chegam diretamente do runtime dos Workers.

Criar o destino

A Cloudflare mantém os destinos no nível da conta, então o mesmo destino atende a todos os Workers da conta.
  1. No painel da Cloudflare, abra Observability > Destinations e selecione Add destination.
  2. Dê um nome ao destino, por exemplo toqan-traces, e defina Destination type como Traces.
  3. Defina OTLP endpoint como https://router.toqan.ai/eu/v2/otel/v1/traces.
  4. Adicione uma entrada Authorization em Custom headers com o valor Bearer <TOQAN_API_KEY>.
  5. Salve e repita com o nome toqan-logs, o tipo Logs e o endpoint https://router.toqan.ai/eu/v2/otel/v1/logs.
Os dois destinos usam o mesmo header, e o exportador aceita o caminho base ou o caminho completo. Consulte o início rápido de observabilidade para o contrato OTLP geral e URLs base para implantações self-hosted.

Referenciar o destino no Wrangler

Informe os nomes dos destinos na configuração do Worker e faça o deploy novamente:
wrangler.jsonc
  • Taxa de amostragem: head_sampling_rate é a fração de requisições exportadas, de 0 a 1. Reduza esse valor em Workers de alto volume.
  • Persistência: persist também mantém uma cópia na Cloudflare. A partir de 1º de dezembro de 2026, traces e logs persistidos contam para o uso do Cloudflare Observability; por isso, o valor acima exporta apenas para o Toqan Router.
Os eventos podem levar vários minutos para chegar ao destino após o primeiro deploy.

Ver traces

Abra Traces para ver o caminho que cada requisição percorre pelo Worker e pelos serviços conectados, e Logs para ver a saída de console.log emitida pelo Worker. As chamadas de modelo são registradas pelo gateway, então aparecem no trace da requisição que as fez.

Traces

Veja cada requisição passando pelo Worker e pelos serviços que ele chama.

Logs

Pesquise a saída de console.log que um Worker emite durante uma execução.