Como criar um agente de programação

(ghuntley.com)

62 pontos por GN⁺ 2025-08-25 | 4 comentários | Compartilhar no WhatsApp

Em 2025, criar você mesmo um agente de programação é um dos melhores projetos que um desenvolvedor individual pode experimentar
Um agente funciona com apenas 300 linhas de código e um loop de tokens de LLM, e ao construí-lo você ganha a chance de deixar de ser consumidor para se tornar um produtor de IA
Os componentes básicos são ferramentas como leitura de arquivos, listagem de arquivos, execução de Bash, edição de arquivos e busca de código, que permitem implementar automações reais
Na escolha de modelos, modelos agentic como Claude Sonnet e Kimi K2 são adequados; quando necessário, modelos oráculo como o GPT podem ser conectados como ferramenta para realizar verificações de nível mais alto
Na prática, produtos comerciais como Amp, Cursor, Claude Code e GitHub Copilot também usam uma estrutura semelhante

Visão geral do workshop

Workshop gratuito conduzido por Geoffrey Huntley, com foco prático em como criar um agente de programação e entender seus princípios
Oferece a oportunidade de comparar estrutura e princípios com assistentes de IA comerciais existentes como Roo code, Cline, Amp, Cursor, Windsurf e OpenCode, além de implementar um você mesmo
Com a experiência de criação, é possível deixar de ser apenas um usuário de IA e evoluir para um desenvolvedor que cria ferramentas de automação usando IA diretamente
A estrutura central é criar funções de agente usando um loop de tokens de LLM em cerca de 300 linhas de código
Ao adicionar primitivas por ferramenta — leitura, listagem de arquivos, execução, edição e busca de código — os exemplos reais de funcionamento e o código estão publicados no repositório GitHub

O que é um agente

Nos últimos tempos, o termo "agente" tem sido usado amplamente, mas seu significado prático e o princípio interno de funcionamento ainda não são claros
À medida que a barreira de entrada para criar agentes diminui, torna-se possível ir além do consumo de IA e crescer como produtor capaz de liderar a automação do trabalho
Em 2025, assim como conceitos básicos de banco de dados como Primary key, os princípios de criação de agentes passam a ser conhecimento essencial
Empresas como a Canva já incentivam o uso de IA em processos de entrevista, e a capacidade de automação com IA tornou-se um elemento central de contratação
Agora, ficar para trás não acontece por causa da IA, mas por não aprender novas ferramentas por meio do próprio desenvolvimento

Princípios centrais do agente de programação

Um agente de programação é composto por apenas 300 linhas de código e um loop de tokens de LLM, executando funções por meio da entrada repetitiva de tokens
O conceito de trabalho concorrente (concurrent work) é importante
- Ex.: mesmo durante uma reunião no Zoom, o agente pode continuar trabalhando em paralelo, aumentando bastante a eficiência
Nem todo LLM é agentic
- 'alta segurança' (ex.: Anthropic, OpenAI)
- 'baixa segurança' (ex.: Grok)
- 'oráculo' (vantajoso para resumo e raciocínio de alto nível)
- 'agentic' (tendência à ação, iteração rápida e chamadas de ferramentas)
O desenvolvedor deve entender as características de cada modelo e escolher o modelo de acordo com o objetivo
Alocar janela de contexto de forma indiscriminada prejudica o desempenho, e é preciso ter em mente que “quanto menos alocado, melhor o resultado”
- Registrar ferramentas MCP em excesso também leva à queda de desempenho
Regra: “Less is more” → para obter desempenho ideal, ferramentas e dados devem ser colocados no contexto apenas na medida do necessário

Fluxo do processo de criação de um agente de programação

1. Registro de ferramentas e chamadas de função
- Por exemplo, registra-se no LLM uma ferramenta de consulta de clima, permitindo que o LLM responda em formato de chamada de função quando a situação for adequada
- MCP (Model Context Protocol) é semelhante a um "banner de informações sobre a função", e só com o registro da descrição da função já é possível fazer a chamada automática
2. Funções essenciais por ferramenta primitiva
- Leitura de arquivo (ReadFile): ao receber um caminho, lê o conteúdo do arquivo para o contexto
- Listagem de arquivos (ListFiles): fornece a lista de arquivos e pastas dentro do diretório
- Execução de comandos (Bash): o LLM executa comandos de shell do sistema e retorna o resultado
- Edição de arquivo (Edit): automatiza a criação e modificação do arquivo especificado
- Busca de código (CodeSearch): faz buscas rápidas em toda a base de código com base em padrões, palavras-chave ou nomes de funções (usando ripgrep)
3. Exemplos e fluxo de resultados
- Ao integrar cada ferramenta ao LLM, é possível automatizar tarefas contínuas apenas com prompts em linguagem natural, como gerar código FizzBuzz → executar e verificar, explorar diretórios → analisar conteúdo etc.
- As funções das ferramentas são chamadas sequencialmente conforme a entrada do usuário ou o cenário, e seus resultados são retornados repetidamente dentro do loop
- Sequência principal de funcionamento do agente: entrada do usuário → decisão sobre chamar ferramenta → execução da ferramenta → alocação do resultado no contexto → repetição

Possibilidades de expansão e open source

Atualmente, a maioria dos agentes de programação funciona com base em ferramentas open source existentes, como o ripgrep
No GitHub, existem projetos de agentes simples, mas poderosos, como SST Open Code e mini-swe-agent, implementados com apenas 100 linhas, que servem de referência para desempenho e estrutura
Recomenda-se que desenvolvedores entendam e apliquem os princípios construindo os próprios agentes, em vez de apenas comparar produtos existentes
Ao aplicar isso ao trabalho real e à automação, criar agentes próprios e difundi-los dentro da organização se torna uma vantagem competitiva

Conclusão e implicações

Agentes de programação não são uma tecnologia complexa, mas sim uma combinação de estrutura de loop simples e conjunto de ferramentas
O ponto central para criar um agente de programação é entender a estrutura e executar rapidamente, e a experiência prática de construção permite responder ativamente às mudanças na tecnologia de IA
Mais importante do que a IA em si é investir em si mesmo, com desenvolvimento contínuo e capacidade de criar ferramentas, o que hoje é a estratégia de crescimento pessoal mais importante
“A ameaça não é a IA tirar o seu trabalho, mas seu colega se armar com agentes, automatizar processos e trabalhar mais rápido”

4 comentários

GN⁺ 2025-08-25

Comentários no Hacker News

Nossa equipe do Princeton SWE-bench criou um agente com cerca de 100 linhas de código que tem bom desempenho no SWE-bench; se tiver interesse, vale dar uma olhada no mini-swe-agent
- Fiquei surpreso com como a estrutura é realmente bem simples; obrigado por compartilhar isso
  O código inteiro, na prática, roda com estes prompts código-fonte do prompt base do agente
```
Your task: {{task}}. Please reply
with a single shell command in
triple backticks.

To finish, the first line of the
output of the shell command must be
'COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT'.
```
- Entre os prompts de exemplo do agente, a parte “1. encontrar e ler os arquivos relevantes no codebase 2. criar um script para reproduzir a issue 3. corrigir a issue 4. verificar a correção com o script 5. testar edge cases” é útil
  Eu também uso um prompt parecido nesse estilo no meu loop de debugging
  A abordagem de “analisar o codebase, listar hipóteses para a causa raiz, ordenar por probabilidade e validar as hipóteses com scripts ou debug logging” ajuda bastante na minha rotina pessoal de resolução de problemas
- Quando o problema está autocontido em um único arquivo, é muito fácil usar LLM para corrigir
  Mas, em codebases gerais, os arquivos e o contexto ficam espalhados por todo lado, então não é fácil entender tudo de acordo com a intenção de design estruturada e a organização feita pelo desenvolvedor
- Palmas pela ótima tentativa, mas o ponto fraco é que não há muitas ferramentas
  A maior parte do código corresponde ao framework do agente, e o código especializado só para SWE não é tanto quanto eu esperava
  Eu também fiz um agente SWE por diversão, então talvez valha ver o autocode
- Adicionei aos materiais de referência como forma de agradecimento
Existe também um “guia de como construir um agente” muito parecido, escrito por Thorsten Ball, no AmpCode How To Guide
No geral, o Amp também é bem interessante
Já não é mais um serviço secreto, mas é bom ver que ferramentas relacionadas a agent coding continuam sendo divulgadas
Acho que, no futuro, vários tipos de software vão incluir esses modelos de agente por padrão
- Isso ficou muito mais fácil de ler, obrigado
- Também foi mencionado que o próprio autor trabalha na Amp
- Ghuntley também trabalha na Amp
Dizem que uma imagem vale mil palavras, mas neste material parece que as imagens estão com 99,6% de desconto
Fico me perguntando o que é isso
- São slides de material para workshop de conferência
  O texto é uma transcrição das falas reais da apresentação
Queria saber se alguém pode confirmar como funciona o uso de ferramentas
Pelo que entendo, Claude, ChatGPT etc. oferecem “ferramentas” via API e, quando chega uma solicitação de chamada de ferramenta, o respondente executa de fato a ferramenta e depois devolve o resultado
Mas, como na prática o modelo é estritamente baseado em texto, fico curioso sobre como a API transforma a resposta do modelo em várias estruturas
Imagino que, no fine-tuning, deve ter havido exemplos em que certas chamadas de ferramenta foram inseridas em blocos especiais para o modelo aprender isso, e depois os servidores do Claude/ChatGPT interpretam esse formato
Gostaria de saber se há documentação sobre isso ou informações sobre tokens especiais usados internamente, e também como impedem que a entrada do usuário abuse desses tokens “responsáveis pelo significado”
- Há documentação pública da Anthropic sobre a implementação
  Anthropic Tool Use Documentation
  Ali fica bem claro que o modelo, na verdade, não opera com “texto”, mas em nível de tokens
  É parecido com a forma como um compilador faz parsing do código-fonte e cria uma sequência de “tokens” como palavras-chave, parênteses e estruturas
  A saída pode incluir metadados junto com as palavras de fato
- Conceitualmente, você entendeu certo
  A única interface real com o LLM são “tokens”, e não há separação entre canal de controle e canal de dados
  Na camada de API do modelo, instruções de chamada de ferramenta e a lista de ferramentas disponíveis são inseridas no prompt, junto com a descrição de cada uma
  Quando é preciso chamar uma ferramenta, o modelo insere um bloco especial na resposta (com tokens especiais, nome da ferramenta e parâmetros), e a camada de API extrai isso e converte para JSON
  O resultado da execução da ferramenta também é inserido codificado com tokens especiais
  A camada de API impede que o próprio input do usuário injete esses tokens
  Os modelos mais recentes (SoTA) passaram por bastante fine-tuning para chamadas de ferramenta, incluindo tanto chamadas genéricas quanto casos específicos de certas ferramentas (por exemplo, o modelo Claude Sonnet sendo especializado nas ferramentas do Claude Code)
  É até impressionante que tudo funcione tão bem; em tool calling, o fine-tuning realmente tem um papel central
  Mesmo sem fine-tuning ainda dá para funcionar, mas a taxa de sucesso cai bastante
- Acho que a suposição de “fizeram fine-tuning para retornar exemplos que precisam de chamada de ferramenta em um bloco especial” está correta
  O modelo é treinado para responder no formato de chamada de ferramenta quando não sabe a resposta ou quando recebe essa instrução
  Há tanto exemplos de chamadas de ferramenta seguindo o formato (o próprio formato) quanto treinamento mais específico para algumas ferramentas
  Por exemplo, o gpt-oss tende a tentar usar ferramenta de busca mesmo sem qualquer menção
  Na documentação da Anthropic também existe uma lista de ferramentas familiares (como text_editor, bash), e é bem provável que tenham treinado separadamente um entendimento mais profundo de como usar essas ferramentas
  Na prática, a estrutura quebra com relativa facilidade e tudo depende de sinais de baixo nível como “tokens especiais ou sequências de tokens”
A frase “se você continuar jogando tokens no loop, surge um agente” vira uma sátira bem realista se você trocar “tokens” por “dinheiro”
No fim, seria como dizer que, se continuar queimando dinheiro, aparece um agente
- Não acho que seja correto dizer que tokens são sempre dinheiro
  Modelos locais também continuam melhorando
  Por enquanto, para ter os melhores resultados ainda é preciso tokens (= dinheiro), mas no futuro isso pode mudar bastante
Quando fica cheio de imagens assim, vira algo muito difícil de ler
Parece um simulador de scroll
Fico me perguntando por que seria necessário qualquer ferramenta além de bash
Coisas como listar arquivos, encontrar e explorar repositórios e editar conteúdo de arquivos não poderiam ser feitas só com bash?
Ou isso é mais como o caso mostrado acima no exemplo do mini-swe-agent?
- Do ponto de vista técnico, só bash já permite uma variedade enorme de tarefas, e eu mesmo já tive sucesso assim
  O interessante é que, quanto mais você restringe as ferramentas, mais criativo o agente fica
  Mas, quando você oferece várias ferramentas treinadas, o modelo já sabe bem como usar cada uma, então o uso de tokens fica mais eficiente e a taxa geral de sucesso também sobe
  Quando só há bash, ele também costuma se enrolar com bashisms, tratamento de argumentos e tratamento de espaços
- Usar ferramentas separadas é muito mais simples do que concentrar tudo em um único bash
  Se tudo for resolvido por bash, você precisará implementar à parte um esquema em que comandos sempre seguros de executar (como listar arquivos) rodem direto, e comandos mais perigosos exijam aprovação do usuário
  Se você oferecer listagem de arquivos como uma ferramenta separada, também pode impedir a exposição de arquivos fora do diretório do projeto
- Na prática, só com a ferramenta bash e uma ferramenta de Edit já dá para fazer um agente de programação funcionar (Edit não é absolutamente obrigatória, mas a ineficiência cresce bastante)
  Ainda assim, partes como busca no código podem ficar difíceis
  Talvez dê para contornar isso ajustando o prompt para fazer o bash usar o ripgrep, por exemplo
- Por que um IDE é necessário? Se tudo pode ser feito pelo shell, por que usar um?
  A UI (interface) existe justamente para oferecer a informação e as ações de que você precisa naquele momento
- Quanto à pergunta de por que há coisas além da ferramenta bash, acho que é porque faz sentido começar com o conjunto mínimo de ferramentas e depois adicionar bash mais tarde, se quiser
Em vez de explicar longamente “como criar um agente”, eu queria ver um projeto real feito por um agente
- Seria ótimo se alguém realmente criasse um agente e compartilhasse no HN como “Show HN”
Alguém consegue explicar o que significam os eixos Oracle, Agent, high safety e low safety?
Testei diretamente com os modelos on-device do Edge e do Chrome (phi4-mini, gemini nano) e fiquei surpreso com como funcionou bem, considerando o tamanho dos modelos
experimento de como construir um agente no dispositivo

crawler 2025-08-25

Dizem que uma imagem normalmente vale 1000 palavras, mas nesse material parece que o valor das imagens foi descontado em 99,6%. Fiquei curioso para saber o que era isso.

Bom demais kkkkkkk eu não tinha entendido o que ele quis dizer, mas quando entrei no link entendi tudo na hora

savvykang 2025-08-25

As miniaturas dos outros posts do blog também são meio toscas, passam uma impressão de que dá zero vontade de clicar.

nemorize 2025-08-25

kkkkkkkkkkkkkkkkkkkkkkkkkkk