> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com o Cloudflare Agents

> Conecte o Cloudflare Agents ao AI Gateway do Toqan Router para rotear entre provedores e exporte traces e logs dos Workers para o Toqan Router via OpenTelemetry.

> [card] [AI Gateway](#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.

> [card] [Observabilidade](#observability)
>
> 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](https://developers.cloudflare.com/agents/) rodam em Workers e Durable Objects e chamam modelos por meio do [AI SDK](https://ai-sdk.dev/docs/introduction). 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:

> [card] Observabilidade completa
>
> Acompanhe as chamadas de modelo e o uso de tokens com traces e analytics detalhados

> [card] Confiabilidade integrada
>
> Fallbacks, novas tentativas e balanceamento de carga automáticos para resiliência em produção

> [card] Otimização de custos
>
> Rastreamento de custos em tempo real e gestão de gastos em cada operação de IA

> [card] 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](https://developers.cloudflare.com/agents/)
* `wrangler` instalado e autenticado

### Instalação

Instale o Agents SDK e o AI SDK com o provedor compatível com OpenAI:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install agents ai @ai-sdk/openai @cloudflare/ai-chat
```

Armazene a chave de API do **Toqan Router** como um secret do Worker:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx wrangler secret put TOQAN_API_KEY
```

### 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 TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createOpenAI } from "@ai-sdk/openai";

export interface Env {
  TOQAN_API_KEY: string;
}

export const gateway = ({ TOQAN_API_KEY }: Env) =>
  createOpenAI({
    baseURL: "https://router.toqan.ai/eu/v3/router",
    apiKey: TOQAN_API_KEY,
  });
```

> **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 TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Agent } from "agents";
import { generateText } from "ai";

import { gateway, type Env } from "./gateway";

export class Assistant extends Agent<Env> {
  async onRequest(request: Request): Promise<Response> {
    const prompt = new URL(request.url).searchParams.get("prompt") ?? "Explain quantum computing in simple terms.";
    const toqan = gateway(this.env);

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

    return Response.json({ text });
  }
}
```

Para um agente de chat com streaming, o `AIChatAgent` do starter recebe o mesmo provedor em `onChatMessage`:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { AIChatAgent } from "@cloudflare/ai-chat";
import { convertToModelMessages, streamText } from "ai";

import { gateway } from "./gateway";

export class ChatAgent extends AIChatAgent {
  async onChatMessage() {
    const result = streamText({
      model: gateway(this.env)("openai/gpt-5.6-sol"),
      messages: await convertToModelMessages(this.messages),
    });

    return result.toUIMessageStreamResponse();
  }
}
```

### Seleção de modelo

Com o **Toqan Router**, use qualquer modelo suportado de mais de 30 provedores alterando o ID do modelo:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { generateText } from "ai";

import { gateway, type Env } from "./gateway";

// Swap the model id for any provider in the catalog:
// anthropic/claude-sonnet-5, google/gemini-2.5-pro, openai/gpt-5.6-luna
export async function ask(env: Env, modelId: string, prompt: string) {
  const toqan = gateway(env);

  const { text } = await generateText({
    model: toqan(modelId),
    prompt,
  });

  return text;
}
```

Consulte [Modelos suportados](/docs/pt-BR/ai-gateway/supported-models.md) 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](/docs/pt-BR/ai-studio/observability/quickstart.md) para o contrato OTLP geral e [URLs base](/docs/pt-BR/reference/base-urls.md) 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:

```json wrangler.jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "observability": {
    "traces": {
      "enabled": true,
      "destinations": ["toqan-traces"],
      "head_sampling_rate": 1,
      "persist": false
    },
    "logs": {
      "enabled": true,
      "destinations": ["toqan-logs"],
      "head_sampling_rate": 1,
      "persist": false
    }
  }
}
```

* **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.

> [card] [Traces](/docs/pt-BR/ai-studio/observability/traces.md)
>
> Veja cada requisição passando pelo Worker e pelos serviços que ele chama.

> [card] [Logs](/docs/pt-BR/ai-studio/observability/logs.md)
>
> Pesquise a saída de `console.log` que um Worker emite durante uma execução.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.