Cloudflare Agents - A plataforma para construir agentes de IA

O que é Cloudflare Agents

Construir agentes de IA personalizados sempre foi um desafio significativo para desenvolvedores. A falta de estado persistente entre execuções exige soluções complexas de gerenciamento de estado, enquanto conexões WebSocket de longa duração geram custos elevados durante períodos de inatividade. Além disso, a integração com múltiplos modelos de linguagem e ferramentas externas adiciona camadas de complexidade que dificultam a manutenção e escala das aplicações.

Cloudflare Agents surge como uma plataforma completa para resolver exatamente esses problemas. Construído sobre a infraestrutura global da Cloudflare, o produto está presente em 330 cidades distribuídas em mais de 125 países, processando diariamente uma média de 93 milhões de requisições HTTP. A plataforma atualmente proxy aproximadamente 20% do tráfego web global, demonstrando sua robustez e confiabilidade em escala empresarial.

O diferencial principal do Cloudflare Agents reside na combinação de três tecnologias fundamentais: Durable Objects para execução stateful com persistência automática, Workers AI para inferência sem servidor em GPUs, e um modelo de precificação baseado em consumo real — você paga apenas pelo que utiliza, sem custos fixos mensais prohibitivos para projetos menores.

Um caso de uso real que ilustra as capacidades da plataforma é o da Knock, empresa que utilizou o Cloudflare Agents SDK para construir um servidor MCP remoto. A solução foi rapidamente implementada e entregue aos clientes, demonstrando a flexibilidade e velocidade de desenvolvimento que a plataforma proporciona.

Funcionalidades Principais do Cloudflare Agents

O Cloudflare Agents oferece um conjunto abrangente de funcionalidades projetadas para simplificar o desenvolvimento de agentes de IA. Cada recurso foi pensado para resolver desafios técnicos específicos que desenvolvedores enfrentam ao construir aplicações inteligentes em produção.

O Agent SDK utiliza classes TypeScript como paradigma fundamental. Ao estender a classe base Agent e utilizar o decorador @callable(), desenvolvedores expõem métodos que podem ser chamados remotamente como RPC. Essa abordagem permite definir o comportamento do agente de forma organizada e tipada, aproveitando todo o ecossistema TypeScript para autocomplete, refactoring e verificação de tipos em tempo de compilação.

O sistema de gerenciamento de estado integrado elimina a necessidade de configurar bancos de dados externos. Cada agente possui acesso a um banco de dados SQLite e armazenamento chave-valor nativo, com estado que persiste automaticamente entre deploys e períodos de hibernação. A sincronização com o cliente acontece em tempo real, sem configuração adicional.

Para casos de uso de chatbots e assistentes virtuais, o AIChatAgent oferece uma solução ready-to-use. Integrado com o SDK ai da Vercel, suporta streaming de respostas via streamText e fornece hooks React (useAgentChat) para integração rápida em interfaces de usuário. A recuperação automática após desconexões garante continuidade na experiência do usuário.

A plataforma suporta múltiplos modelos de IA sem lock-in. Além dos modelos nativos do Workers AI (Llama 3.1/3.2/3.3, Mistral, DeepSeek R1, Gemma, Qwen), é possível conectar modelos de terceiros como OpenAI GPT-4, Anthropic Claude e Google Gemini através do AI Gateway, permitindo flexibilidade na escolha do modelo ideal para cada tarefa.

O sistema de ferramentas permite que agentes interajam com o mundo exterior. Métodos decorados com @callable() funcionam como ferramentas que podem ser chamadas por LLMs, habilitando automação de workflows complexos. A integração com MCP (Model Context Protocol) expande essas capacidades para conectar com servidores Slack, GitHub, databases e outros serviços externos.

A comunicação em tempo real é suportada via WebSocket com hibernação inteligente. Quando não há atividade, o agente entra em modo de hibernação e para de acumular custos de tempo de CPU, mas mantém a conexão ativa com o cliente. Isso reduz drasticamente custos operacionais para aplicações que não requerem processamento constante.

Para tarefas programadas, o Scheduler API nativo suporta expressões cron e execução atrasada, permitindo automação de relatórios, sincronização de dados e lembretes periódicos sem necessidade de serviços externos.

Por fim, o Browser Rendering API permite iniciar navegadores headless para web scraping, capturas de tela e automação de interações web, expandindo as capacidades do agente para cenários que requerem conteúdo dinâmico.

Arquitetura Técnica e Características Principais

A arquitetura do Cloudflare Agents foi projetada para oferecer escalabilidade horizontal massiva mantendo simplicidade operacional. Compreender os componentes técnicos fundamentais ajuda desenvolvedores a tomar decisões arquiteturais informadas para seus projetos.

O núcleo da plataforma são os Durable Objects, uma tecnologia que transforma a forma como aplicações stateful são construídas. Cada agente executa em um Durable Object, que funciona como um microsservidor com estado persistente. Diferente de funções serverless tradicionais que são efêmeras, Durable Objects mantêm memória e dados entre invocações, eliminando a necessidade de camadas de cache externas ou sincronização de estado complexa.

O Workers AI fornece inferência de modelos de linguagem sem gerenciamento de infraestrutura. Os modelos são executados em GPUs otimizadas, com billing baseado em Neurons — uma unidade que mede o processamento real de GPU utilizado. Essa abordagem é significativamente mais econômica que instance-based pricing, pois você paga apenas pelo tempo de CPU efetivamente consumido, não pelo wall time incluindo I/O e espera.

Para aplicações que requerem busca semântica, o Vectorize oferece um banco de dados vetorial integrado. Ele permite armazenar embeddings e realizar buscas por similaridade eficientes, essencial para implementação de RAG (Retrieval-Augmented Generation) que fornece contexto relevante aos LLMs.

O D1 complementa o ecossistema com um banco de dados SQL serverless baseado em SQLite. A integração com Durable Objects permite que cada agente acesso dados relacionais diretamente, com replicação automática e zero configuração de infraestrutura.

Para workflows de múltiplas etapas, o Workflows garante execução confiável mesmo para tarefas de longa duração. Com state machine integrada, retry automático e persistência de estado, é possível construir processos que executam por dias ou semanas sem perda de progresso.

A integração com MCP permite que agentes exponham ferramentas para outros agentes ou se conectem a servidores MCP externos como Slack, GitHub e databases. Isso cria um ecossistema interoperável onde diferentes agentes podem colaborar.

Os números de performance demonstram a capacidade da plataforma: é possível escalar para dezenas de milhões de instâncias simultâneas, com WebSocket hibernation que para completamente a cobrança de duração quando inativo. A otimização de GPU garante que apenas tempo de CPU útil seja cobrado, excluindo períodos de espera.

Quick Start

Iniciar com Cloudflare Agents é simplificado ao máximo. Com apenas alguns comandos, desenvolvedores têm um agente funcional rodando localmente e pronto para deploy em produção.

Os pré-requisitos são mínimos: apenas Node.js 18+ e uma conta Cloudflare. Não é necessário configurar infraestrutura, bancos de dados ou servidores.

A instalação segue três passos simples:

npm i agents
npx create-cloudflare@latest --template cloudflare/agents-starter
cd agents-starter && npm install
npm run dev

O comando create-cloudflare gera um projeto completo com o exemplo Lunch Agent, que demonstra todos os conceitos fundamentais da plataforma. O projeto já inclui configuração de TypeScript, dependências necessárias e scripts de build.

O exemplo Lunch Agent ilustra os principais conceitos em ação:

export class LunchAgent extends Agent<Env, LunchState> {
  @callable()
  async nominateRestaurant(restaurantName: string) {
    // Lógica de indicação de restaurante
  }
  
  // Agendamento de tarefas
  this.schedule('weekdays at 11:30pm', 'chooseLunch');
  this.schedule('daily at 5pm', 'resetLunch');
}

O agente define métodos callable usando decorators, gerencia estado internamente, e configura tarefas agendadas com expressões cron simples. Todo o código é executado no edge, próximo aos usuários, para mínima latência.

Para deploy em produção, o comando único npx wrangler deploy distribui o agente para a rede global da Cloudflare. O código automaticamente replica para todos os datacenters, garantindo baixa latência independente da localização do usuário.

Plano de Precificação do Cloudflare Agents

A transparência de custos é fundamental para planejamento orçamentário em projetos de qualquer escala. Cloudflare Agents oferece uma estrutura de precificação previsível comgenerosos limites gratuitos para desenvolvimento e testes.

Planos Workers

Custos adicionais para requisições excedentes são de $0.30 por milhão de requisições e $0.02 por milhão de CPU ms utilizados.

Workers AI - Preços por Modelo

O modelo de cobrança por Neurons unifica diferentes modelos em uma única métrica. O tier gratuito inclui 10.000 Neurons diários, suficiente para desenvolvimento e testes extensivos. Excedentes custam $0.011 por千 Neurons.

Durable Objects

• Requisições: 1M/mês no Paid (100K/dia no Free)
• Duração: 400K GB-s/mês (13K GB-s/dia no Free)

Estratégias de Otimização de Custo

Três estratégias principais maximizam o retorno do investimento na plataforma:

A cobrança por CPU time significa que períodos de espera de I/O não são cobrados — apenas tempo de CPU ativo conta. Isso é especialmente vantajoso para aplicações com muitas operações de rede.

A hibernação WebSocket para completamente a cobrança de duração quando não há atividade, mas mantém a conexão aberta. Ideal para chatbots e aplicações colaborativas com períodos de inatividade.

A ausência de egress fees em R2, D1 e outros storage significa que dados transferidos para fora não geram custos adicionais, diferentemente de outros provedores cloud.

Ecossistema e Integrações

Cloudflare Agents não é uma solução isolada — está inserido em um ecossistema rico que amplia suas capacidades através de integrações estratégicas com ferramentas e serviços amplamente utilizados pela comunidade de desenvolvedores.

O suporte a MCP (Model Context Protocol) representa uma das integrações mais poderosas. O protocolo permite que agentes exponham ferramentas para outros agentes de forma padronizada. O ecossistema MCP já inclui servidores prontos para Slack, GitHub, PostgreSQL, MySQL e numerous outros serviços. Além de consumir servidores MCP externos, desenvolvedores podem construir seus próprios servidores MCP remotos usando Cloudflare Agents — o caso da Knock demonstra como essa abordagem simplifica a entrega de ferramentas IA para clientes.

A integração com modelos de terceiros acontece através do AI Gateway. Essa camada de abstração permite conectar modelos OpenAI, Anthropic Claude e Google Gemini mantendo interface unificada. O AI Gateway também fornece rate limiting, caching e analytics centralizados independentedo modelo utilizado.

O conjunto de ferramentas para desenvolvedores inclui o Workers Playground para testes rápidos sem deploy, CLI Wrangler para automação e integração CI/CD, e suporte a Chrome DevTools para debugging de Workers. A API Dashboard fornece visualização de métricas, logs e traces em tempo real.

A comunidade ativa é um diferencial importante. O Discord da Cloudflare para desenvolvedores conta com dezenas de milhares de membros ativos, os exemplos no GitHub (Lunch Agent, Chat Agent, Slack Agent) fornecem templates prontos para diferentes casos de uso, e a documentação extensiva cobre todos os aspectos da plataforma.

Para implementações empresariais, a plataforma oferece SOC 2 certification e conformidade GDPR, garantindo compliance para aplicações sensíveis. A integração com sistemas corporativos existentes é facilitada através de APIs RESTful e webhooks.

Perguntas Frequentes

npm i agents
npx create-cloudflare@latest --template cloudflare/agents-starter
cd agents-starter && npm install
npm run dev