Como usar Cloudflare Workers AI

O que é

O Cloudflare Workers AI é um provedor de IA que pode ser escolhido ao configurar um agente do Zé Bot. Ele oferece modelos abertos na rede da Cloudflare, com cobrança por neurônios e é acessado por um endpoint OpenAI compatível: https://api.cloudflare.com/client/v4/accounts/SEU_ACCOUNT_ID/ai/v1.

Antes de começar

Ter uma conta no Cloudflare Workers AI.
Criar uma chave de API no painel da Cloudflare.
Ter conexão com a internet; o Zé Bot não intermedeia a cobrança do provedor.
Ter o ID da conta Cloudflare e um API token com permissão Workers AI.

Como conectar

Abra um agente existente ou crie um novo.
No seletor de provedor e modelo, escolha Cloudflare Workers AI.
Confira o Endpoint. O padrão é https://api.cloudflare.com/client/v4/accounts/SEU_ACCOUNT_ID/ai/v1.
Cole a Chave de API no campo do agente. A chave fica no cofre seguro do sistema e não aparece no histórico.
Escolha o Modelo. O padrão é @cf/openai/gpt-oss-120b.
Envie uma tarefa curta para validar a conexão, como “Liste três ideias para organizar minha semana”.

Como escolher o modelo

O Zé Bot tenta consultar o catálogo https://api.cloudflare.com/client/v4/accounts/SEU_ACCOUNT_ID/ai/v1/models com a chave do agente. Quando o provedor responde, o campo de modelo mostra os IDs disponíveis e também aceita um ID digitado. Quando o catálogo não responde, a lista de reserva traz @cf/openai/gpt-oss-120b, @cf/meta/llama-4-scout-17b-16e-instruct, @cf/deepseek-ai/deepseek-v4.1-flash-1017 e @cf/qwen/qwen3.8-27b.

Os IDs de modelo são do provedor e podem mudar sem aviso. Se um modelo não existir mais, escolha outro no catálogo ou consulte a documentação oficial do Cloudflare Workers AI.

Como criar um agente com Cloudflare Workers AI

Em Agentes, crie um agente ou abra um existente.
Em Provedor, escolha Cloudflare Workers AI.
Informe ou confirme o endpoint e a chave de API.
Escolha o modelo e, se o provedor oferecer, o nível de raciocínio.
Envie uma tarefa curta e confira a resposta antes de usar o agente em trabalho real.

Limites

A Cloudflare usa a cota diária de neurônios do Workers AI e exige um API token com permissão de Workers AI.
O Workers AI não publica o catálogo /models no formato OpenAI; por isso a lista de reserva e o ID digitado são o caminho normal.
O runtime HTTP envia a conversa como Chat Completions e não encaminha ferramentas MCP. Para agentes que precisam usar ferramentas e arquivos do workspace, prefira Codex, Claude, OpenCode ou outro provedor ACP.
O Zé Bot não controla cotas, limites de taxa nem preços do provedor. Consulte o painel do Cloudflare Workers AI.

Problemas comuns

A chave é recusada com 401 ou 403

Confira se a chave foi copiada inteira, se pertence à conta certa e se tem permissão para o modelo escolhido. Chaves de plano de codificação podem não valer para a API padrão.

O catálogo de modelos não aparece

O Zé Bot mantém a lista de reserva e aceita o ID digitado. Se o provedor responder 404 ou 405 em /models, a conexão ainda pode funcionar; teste com uma tarefa curta.

A resposta demora ou retorna 429

O provedor aplicou limite de taxa ou a conta está sem cota. Aguarde, reduza a frequência ou ajuste o plano no painel do provedor.

O modelo não é encontrado

O ID pode ter sido descontinuado ou o modelo pode não estar liberado para a conta. Atualize o modelo no agente e consulte a documentação oficial.

O endpoint da Cloudflare pede o ID da conta

O valor padrão traz SEU_ACCOUNT_ID. Troque esse trecho pelo ID da conta Cloudflare antes de salvar o agente. Sem isso, a chamada não encontra a conta.

Privacidade e segurança

A chave de API fica no cofre seguro do sistema operacional e não é enviada ao renderer. Ao executar uma tarefa, as instruções do agente e o prompt do turno são enviados ao endpoint do Cloudflare Workers AI; o provedor processa esses dados conforme a política dele. Memórias, arquivos e ferramentas locais continuam no seu computador.

Próximos passos

Leia o lançamento em /blog/cloudflare.
Veja os outros manuais em /manual.