# Cloudflare AI Gateway + Vectorize: Como Implementar Agentes de IA na Prática

**Categoria:** Infraestrutura | **Tempo de leitura:** 15 min | **Autor:** Equipe ITC Service

---

Agentes de IA em produção exigem mais do que chamadas diretas à API da OpenAI. Você precisa de cache, rate limiting, observabilidade e RAG confiável. Este tutorial mostra como configurar AI Gateway, Vectorize e Workers na Cloudflare para rodar agentes serverless com custo previsível e latência global.

## Por que não chamar a API diretamente?

Chamadas diretas à OpenAI/Anthropic em produção causam:

- **Custo imprevisível**: sem cache, cada request paga token cheio
- **Sem observabilidade**: não sabe qual prompt falhou ou custou mais
- **Rate limit frágil**: retry manual, sem fila ou backoff inteligente
- **Latência variável**: sem edge caching, usuário longe sofre
- **Sem RAG nativo**: precisa orquestrar embedding + busca + contexto manualmente

O AI Gateway resolve os 4 primeiros. Vectorize resolve o último. Juntos, formam a stack mínima para agentes em produção.

## Passo 1: Criar AI Gateway no Dashboard

1. Acesse Cloudflare Dashboard → AI → AI Gateway
2. Clique "Create Gateway"
3. Nomeie (ex: `itc-agents-prod`)
4. Copie o endpoint gerado: `https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai`

Esse endpoint é drop-in replacement da API da OpenAI. Basta trocar a base URL no seu código:

```javascript
// Antes
const openai = new OpenAI({ apiKey: process.env.OPENAI_KEY });

// Depois
const openai = new OpenAI({
apiKey: process.env.OPENAI_KEY,
baseURL: 'https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai'
});
```

**Benefício imediato:** Todas as chamadas passam a ter logs, métricas e cache sem mudar uma linha de lógica.

## Passo 2: Configurar Cache Semântico

No dashboard do AI Gateway → Settings → Caching:

- **Cache TTL**: 3600s (1 hora) para prompts determinísticos
- **Semantic Cache**: ON para prompts similares (embedding-based)
- **Cache Key**: incluir `user_id` se respostas forem personalizadas

O semantic cache usa embeddings internos da Cloudflare. Prompts com >90% similaridade hitam cache. Reduz custo em 30-60% para agentes com perguntas recorrentes.

## Passo 3: Criar Índice Vectorize para RAG

```bash
# Via Wrangler CLI
wrangler vectorize create itc-knowledge-base --dimensions=1536 --metric=cosine
```

Ou via dashboard: AI → Vectorize → Create Index.

**Dimensões:** 1536 para OpenAI embeddings, 768 para BGE-M3, 1024 para Cohere. Verifique a documentação do modelo.

### Ingestão de Documentos

```javascript
// worker.js - endpoint de ingestão
export default {
async fetch(request, env) {
const { text, metadata } = await request.json();

// Gera embedding via AI Gateway
const embedding = await env.AI.run('@cf/baai/bge-m3', { text });

// Insere no Vectorize
await env.VECTORIZE.upsert([{
id: crypto.randomUUID(),
values: embedding.data[0],
metadata: { ...metadata, created_at: Date.now() }
}]);

return Response.json({ ok: true });
}
};
```

## Passo 4: Agente com RAG no Worker

```javascript
// worker.js - agente com RAG
export default {
async fetch(request, env) {
const { query } = await request.json();

// 1. Busca documentos relevantes
const queryEmbedding = await env.AI.run('@cf/baai/bge-m3', { text: query });
const matches = await env.VECTORIZE.query(queryEmbedding.data[0], { topK: 5 });

// 2. Monta contexto
const context = matches.matches
.map(m => m.metadata.content)
.join('\n\n');

// 3. Chama LLM via AI Gateway (com cache!)
const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
messages: [
{ role: 'system', content: `Use apenas o contexto fornecido:\n${context}` },
{ role: 'user', content: query }
]
});

return Response.json({ answer: response.response, sources: matches.matches.map(m => m.metadata.source) });
}
};
```

## Passo 5: Observabilidade e Alertas

No AI Gateway → Logs:

- Filtre por `status >= 400` para erros
- Agrupe por `model` para ver custo por modelo
- Crie alertas para latency p99 > 5s ou error rate > 5%

Exporte para Grafana/Datadog via webhook ou API de logs.

## Custos Reais (Setembro 2026)

| Componente | Free Tier | Paid (por unidade) |
|------------|-----------|-------------------|
| AI Gateway requests | 10k/dia | $0.30/1M requests |
| Vectorize storage | 100MB | $0.04/GB/mês |
| Vectorize queries | 10k/dia | $0.05/1M queries |
| Workers invocations | 100k/dia | $0.30/1M |
| BGE-M3 embeddings | 10k/dia | Incluído no Workers AI |

**Exemplo real:** Agente com 50k requests/dia, 10GB vectors, 100k queries/dia ≈ $15-25/mês total. Comparado a $200-500/mês chamando OpenAI direto sem cache.

## Checklist de Produção

- [ ] AI Gateway criado e endpoint configurado
- [ ] Semantic cache ativado com TTL apropriado
- [ ] Vectorize index criado com dimensões corretas
- [ ] Pipeline de ingestão testado com documentos reais
- [ ] Agente respondendo com fontes citadas
- [ ] Alertas de erro e latência configurados
- [ ] Rate limiting por user/API key ativo
- [ ] Logs exportados para sistema externo
- [ ] Teste de carga validado (p99 < 2s)

## Erros Comuns

1. **Usar modelo de embedding errado no Vectorize**: dimensões incompatíveis = query falha silenciosamente
2. **Esquecer metadata no upsert**: sem metadata, não filtra por tenant/data/source
3. **Não versionar prompts**: mudança de prompt invalida semantic cache sem aviso
4. **Ignorar cold start do Vectorize**: primeira query após idle tem 200-500ms extra
5. **Hardcodar API key no Worker**: use Secrets do Cloudflare, nunca variáveis de ambiente plaintext

## Como a ITC Service implementa isso

Setup completo de AI Gateway + Vectorize + Worker em 48h. Inclui pipeline de ingestão, agente funcional, dashboard de observabilidade e documentação de runbook. Treinamento opcional para sua equipe manter e evoluir.

**[Agendar implementação de agentes IA →](/contato)**

---

*Tags: cloudflare, ai gateway, vectorize, agentes ia, rag, serverless, workers*
*CTA: Implementação gerenciada de agentes IA*