Projetando loops de agentes

• Agentes de programação como Claude Code da Anthropic e Codex CLI da OpenAI melhoram fundamentalmente a utilidade dos LLMs para gerar código funcional, pois podem executar código diretamente, corrigir erros, explorar implementações existentes e encontrar soluções eficazes por meio de experimentação
• A técnica central para aproveitar ao máximo o potencial dessas ferramentas é o projeto de loops de agentes; ao reduzir problemas para um agente de programação com um objetivo claro e um conjunto de ferramentas, é possível entendê-lo como uma ferramenta capaz de encontrar soluções eficazes por força bruta
• A definição de um agente LLM é executar ferramentas dentro de um loop para atingir um objetivo, e a habilidade para usá-lo bem está em projetar com cuidado as ferramentas e o loop que o agente irá usar
• O modo YOLO (em que todos os comandos são aprovados por padrão) é arriscado, mas é essencial para obter os resultados mais produtivos por força bruta; para executá-lo com segurança, é possível escolher entre sandboxes com Docker, outros ambientes computacionais como GitHub Codespaces, ou simplesmente aceitar o risco
• Escolher as ferramentas certas (comandos de shell e pacotes), emitir credenciais com escopo estrito (ambientes de teste, limites de orçamento) e aplicar isso a problemas com critérios claros de sucesso e necessidade de tentativa e erro (depuração, otimização de desempenho, upgrades de dependências, otimização de contêineres) são os princípios centrais do projeto de loops de agentes

---

A diversão do modo YOLO

• Os riscos dos agentes

  • Agentes são inerentemente arriscados
    • Podem tomar decisões erradas ou ser vítimas de ataques maliciosos de prompt injection
    • Chamadas de ferramentas podem causar resultados prejudiciais
  • A ferramenta mais poderosa dos agentes de programação é “executar este comando no shell”, então um agente defeituoso pode fazer qualquer coisa que o usuário poderia fazer ao executar comandos diretamente
  • Citação de Solomon Hykes:

    Agentes de IA são LLMs destruindo o ambiente dentro de um loop

• Limitações do modo de aprovação padrão

  • Agentes de programação como o Claude Code respondem a isso configurando como padrão o pedido de aprovação para quase todo comando que executam
  • Isso é um pouco tedioso, mas, mais importante, reduz drasticamente a eficácia de resolver problemas por força bruta

• Modo YOLO

  • Cada ferramenta oferece sua própria versão de modo YOLO, em que tudo é aprovado por padrão
  • É extremamente arriscado, mas também é essencial para obter os resultados mais produtivos

• Três principais riscos do modo YOLO sem supervisão

  • 1. Comandos de shell ruins: apagar ou danificar algo importante
  • 2. Ataques de exfiltração: roubar arquivos ou dados que o agente consegue ver (código-fonte ou segredos armazenados em variáveis de ambiente)
  • 3. Ataques por proxy: usar a máquina como proxy para disfarçar a origem de um DDoS ou de outros ataques contra terceiros

Opções para executar o modo YOLO

• Opção 1: sandbox de segurança

  • Executar o agente em uma sandbox de segurança que limite os arquivos e segredos aos quais ele pode acessar, bem como as conexões de rede que pode criar
  • Existe a possibilidade de escape de contêiner, mas usar Docker ou as novas ferramentas de contêiner da Apple é um risco aceitável para a maioria das pessoas
  • Documentação do modo Safe YOLO da Anthropic:
    • usar --dangerously-skip-permissions em um contêiner sem acesso à internet
    • fornece uma implementação de referência usando Docker Dev Containers
    • restringir o acesso à internet a uma lista de hosts confiáveis é uma boa forma de evitar o roubo de código-fonte privado

• Opção 2: usar o computador de outra pessoa (preferido)

  • Mesmo que o agente saia do controle, o dano é limitado
  • Recomenda-se usar GitHub Codespaces:
    • oferece ambientes completos em contêiner sob demanda, acessíveis pelo navegador
    • oferece um nível gratuito generoso
    • se algo der errado, no pior caso uma máquina do Microsoft Azure em algum lugar vai gastar CPU, e o código feito checkout nesse ambiente pode ser exfiltrado por um atacante, ou código ruim pode ser enviado para o repositório GitHub conectado
  • Outras ferramentas do tipo agente que executam código no computador de outra pessoa:
    • modo Code Interpreter do ChatGPT e do Claude
    • Codex Cloud da OpenAI

• Opção 3: aceitar o risco

  • Tentar evitar exposição a possíveis fontes de instruções maliciosas e torcer para detectar erros antes que causem danos
  • A opção que a maioria das pessoas escolhe

Escolhendo as ferramentas certas para o loop

• Depois de garantir um modo YOLO seguro

  • O próximo passo é decidir quais ferramentas devem estar disponíveis para o agente de programação

• Prioridade para comandos de shell

  • Neste ponto é possível misturar MCP (Model Context Protocol), mas normalmente é mais produtivo pensar em termos de comandos de shell
  • Agentes de programação são realmente bons em executar comandos de shell
  • Se o ambiente permitir o acesso de rede necessário, eles também podem buscar pacotes adicionais no NPM, PyPI etc.
  • Também é importante garantir que o agente rode em um ambiente em que a instalação de pacotes aleatórios não estrague coisas no seu computador principal

• Uso do arquivo AGENTS.md

  • Em vez de depender de MCP, prefere-se criar um arquivo AGENTS.md (ou equivalente) com detalhes sobre os pacotes que devem ser usados
  • Exemplo: em um projeto para tirar capturas de tela de vários sites, instalar sua própria ferramenta de CLI shot-scraper e adicionar o seguinte em AGENTS.md:

    Para tirar uma captura de tela, execute:  
    
    shot-scraper http://www.example.com/ -w 800 -o example.jpg  
    

  • Esse único exemplo já basta para o agente inferir como substituir a URL e o nome do arquivo para outras capturas de tela

• Aproveitando ferramentas existentes

  • Bons LLMs já sabem usar uma variedade embaraçosamente grande de ferramentas existentes
  • Se você disser “use playwright python” ou “use ffmpeg”, a maioria dos modelos consegue usar isso com eficiência
  • Como operam em loop, normalmente conseguem se recuperar dos erros cometidos no início e descobrir a ordem correta sem instruções adicionais

Emitindo credenciais com escopo estrito

• A necessidade de credenciais

  • Além de expor os comandos corretos, é preciso considerar quais credenciais devem ser expostas a esses comandos
  • Idealmente, nenhuma credencial seria necessária (muitas tarefas podem ser realizadas sem login ou chave de API), mas alguns problemas exigem acesso autenticado

• Duas recomendações principais

  • 1. Fornecer credenciais para um ambiente de teste ou staging
    • um ambiente onde eventuais danos possam ser bem contidos
  • 2. Definir limites de orçamento
    • se as credenciais puderem gastar dinheiro, estabeleça um limite de orçamento rígido

• Caso real: investigação no Fly.io

  • Investigar tempos lentos de cold start em uma aplicação scale-to-zero rodando no Fly.io
  • Permitir que o Claude Code edite diretamente o Dockerfile, faça deploy na conta Fly e meça quanto tempo leva para iniciar

  • Configuração segura

    • No Fly, é possível criar uma organização, definir um limite de orçamento para essa organização e emitir uma chave de API do Fly que só possa criar ou modificar apps dentro dessa organização
    • Criar uma organização dedicada apenas para essa investigação
    • Definir um orçamento de $5
    • Emitir a chave de API e soltar o Claude Code
  • Embora os resultados não tenham sido úteis o bastante nesse caso específico, foi o projeto que primeiro mostrou que “projeto de loops de agentes” é uma habilidade importante a desenvolver

Quando projetar um loop de agente

• Padrões de problemas adequados

  • Nem todo problema responde bem a esse padrão de trabalho
  • O que vale procurar são problemas com critérios claros de sucesso e nos quais encontrar uma boa solução provavelmente exigirá tentativa e erro (potencialmente um pouco tediosa)
  • Sempre que você pensar “aff, vou ter que tentar muitas variações aqui”, esse é um forte sinal de que vale a pena experimentar um loop de agente

• Exemplos concretos

  • Depuração

    • Um teste falha e é preciso investigar a causa raiz
    • Um agente de programação que já consegue executar testes pode fazer isso sem configuração adicional

  • Otimização de desempenho

    • Uma query SQL está lenta demais; adicionar um índice ajudaria?
    • O agente pode fazer benchmark da query e, (em um ambiente de desenvolvimento isolado!) adicionar e remover índices para medir o impacto

  • Upgrade de dependências

    • O projeto está atrasado em vários upgrades de dependências
    • Se a suíte de testes for robusta, um loop de agente pode fazer todos os upgrades e aplicar as pequenas atualizações necessárias para acomodar mudanças importantes
    • Forneça cópias das release notes relevantes, ou garanta que o agente saiba onde encontrá-las sozinho

  • Otimização do tamanho de contêineres

    • Um contêiner Docker está desconfortavelmente grande
    • O agente pode testar diferentes imagens base e iterar no Dockerfile para tentar reduzi-lo, mantendo os testes aprovados

• Tema comum: testes automatizados

  • O tema comum em tudo isso são os testes automatizados
  • O valor obtido com agentes de programação e outras ferramentas de código com LLM é amplificado enormemente por uma boa suíte de testes que passe de forma limpa
  • Felizmente, os LLMs são excelentes para acelerar o processo de montar isso quando ainda não existe

Ainda é uma área muito nova

• O projeto de loops de agentes é uma habilidade muito nova
  • O Claude Code foi lançado pela primeira vez em fevereiro de 2025
• Há esperança de que dar um nome claro a isso ajude a ter conversas produtivas sobre o tema
• Ainda há muito mais a descobrir sobre como usar essas ferramentas da forma mais eficaz possível