Como criar um Agente no Cloudflare Agents passo a passo

Separe o que você precisa antes de começar

Antes de criar o agente, confira quatro pré-requisitos: Node.js v20+, conta Cloudflare, terminal ou linha de comando e conhecimento básico de JavaScript. O workshop oficial utiliza também uma chave da OpenAI, porque o Agent Starter transmite respostas do modelo por padrão. Se o comando npm não aparecer no seu PC, em geral a causa é a ausência do Node.js instalado. Se surgir erro de permissão ao instalar ferramentas globais, a instrução mostrada é usar sudo npm install -g wrangler no macOS ou Linux. Já em caso de erro de build, a correção descrita é apagar a pasta node_modules e rodar npm install de novo. Com esses pontos resolvidos logo no início, o processo tende a fluir sem interrupções nas etapas seguintes.

O Agent Starter usado no passo a passo depende de uma chave válida da OpenAI para funcionar no fluxo padrão de respostas em streaming.

Crie o projeto do agente com o template oficial

Abra o terminal na pasta em que você pretende guardar o projeto e execute o comando oficial de criação do starter. O nome do exemplo usado no material é my-first-agent. Na sequência, entre na pasta criada, instale as dependências e prepare o ambiente local. Os comandos exibidos são estes:

Esse template monta uma aplicação Cloudflare Workers baseada no Agent Starter, com as interfaces mais comuns para agentes já incluídas. Na prática, você não começa do zero: o projeto nasce com chat web, ferramentas e estrutura pronta para explorar estado, chamadas de modelo e agendamento. O fluxo inicial fica bem mais direto, sobretudo para quem quer entender a lógica do Cloudflare Agents antes de escrever ferramentas próprias ou integrar serviços externos no código.

Configure a chave da OpenAI e inicie o servidor

Com o projeto criado e as dependências instaladas, o próximo passo é atualizar a variável OPENAI_API_KEY com uma chave válida e iniciar o ambiente de desenvolvimento com npm start. O material não detalha a tela ou o arquivo exato de edição dessa variável, então o ponto explicitado é a exigência de preencher OPENAI_API_KEY antes de rodar o starter no fluxo padrão. Em seguida, use o comando abaixo:

Quando tudo estiver configurado do jeito esperado, a saída exibida no terminal é Local server running at http://localhost:5173. Essa linha indica que o agente já está acessível localmente por uma interface web de chat. O que foi criado nesse momento é um app baseado em Cloudflare Workers que conversa com um agente com estado. A partir daí, o starter começa a transmitir respostas do modelo em tempo real, usando a chave de API fornecida.

Se o servidor local parar durante os testes, o próprio material instrui a simplesmente iniciar de novo com npm start.

Teste as ferramentas do agente no chat

Depois de abrir o endereço local, use a interface de chat para checar o comportamento do agente. O starter oficial inclui exemplos prontos de ferramentas. Um dos testes sugeridos é perguntar: What is the time in Vegas? A resposta esperada é uma chamada de ferramenta concluída usando getLocalTime, com um resultado como It is currently 10:00 AM in Las Vegas. Em seguida, a recomendação é perguntar: What is the current weather in Las Vegas? Nesse cenário, o comportamento muda: a chamada da ferramenta fica pausada aguardando verificação. A interface exibe os botões Approve e Reject, e só depois da aprovação a ferramenta é executada. Esse contraste deixa claros dois fluxos do Cloudflare Agents: ferramentas que rodam automaticamente e ferramentas com human in the loop, ou seja, dependentes de aprovação humana antes da execução.

Entenda como as ferramentas foram definidas no projeto

Para aprofundar o entendimento além do teste no chat, abra o arquivo src/tools.ts. Esse arquivo reúne os exemplos de declaração de ferramentas usados pelo starter. O material chama atenção para o fato de que a ferramenta getLocalTime inclui uma função execute fornecida diretamente na definição. Já em getWeatherInfomration, a ausência da função execute é o que determina o requisito de aprovação humana. O mesmo arquivo também exporta um objeto chamado executions. O ponto central é que as chaves desse objeto precisam corresponder ao nome da ferramenta. Depois da aprovação no chat, a função correspondente em executions é a que entra em ação. Esse desenho separa a intenção da ferramenta da execução real, útil para tarefas que exigem confirmação antes de alterar dados ou acionar serviços externos sensíveis.

Experimente tarefas agendadas no seu agente

O Agent Starter inclui também testes de agendamento, um dos recursos centrais do framework. Com o servidor ativo, peça no chat algo como In twenty seconds say supdawg. O esperado é ver tarefas agendadas aparecendo no histórico da conversa. Em seguida, teste um agendamento recorrente com Every 15 seconds say supdawg. O chat deve indicar que a tarefa foi programada para repetição em intervalo fixo. Para interromper, use o comando em linguagem natural Cancel the recurring task. O material informa que o cancelamento é conduzido com ferramentas do próprio starter. Em src/tools.ts, a implementação de getScheduledTasks e cancelScheduledTask usa métodos RPC baseados na resposta de getCurrentAgent. Isso expõe como o agente mantém estado, agenda ações futuras e, depois, consegue alterar ou cancelar o que já estava previsto no fluxo.

Ao fim desses testes, você terá um agente funcional no Cloudflare Agents com chat local, ferramentas automáticas, aprovação humana e tarefas agendadas.