Build a Research Agent

Cada módulo neste caminho foi construindo em direção a uma pergunta: como é um sistema agêntico confiável quando você o executa de verdade? Este capstone responde com o mesmo padrão que uso no meu harness do SDLC — um agente linear de orquestração de tarefas que roda no meu Mac Mini, acionado por um arquivo de especificação simples em Markdown.

O agente faz quatro coisas, em ordem estrita:

1. Ler uma especificação — a descrição da tarefa vive no disco como um arquivo de texto simples.
2. Planejar com Claude — pedir ao claude-sonnet-4-6 que decompõe a especificação em etapas numeradas.
3. Executar cada etapa — uma chamada de ferramenta por etapa, com o histórico completo passado adiante.
4. Escrever um relatório de status — resumir o que foi feito.

Sem subtarefas paralelas, sem handoff entre agentes especializados, sem framework de orquestração. A simplicidade é o ponto. O módulo 06 dá a teoria de por que isso funciona; este módulo dá o código funcionando.

Pense no agente como um empreiteiro que lê um briefing de projeto, escreve uma lista numerada de tarefas, trabalha do topo para baixo enquanto mantém notas sobre cada item concluído, e então arquiva um relatório de conclusão. As notas se acumulam — cada item na lista é informado por tudo que foi feito antes. Esse é o princípio de contexto compartilhado tornado concreto.

O agente começa com um arquivo de especificação em texto simples. No harness do SDLC, isso é uma descrição de tarefa em Markdown; para este módulo qualquer arquivo de texto descrevendo uma tarefa funcionará.

Copie este bloco, crie um task-spec.md com qualquer descrição de tarefa e execute. O objeto client é tudo que você precisa — sem wrapping adicional do SDK. Este é seu primeiro passo executável, e verifica sua ANTHROPIC_API_KEY antes de você escrever mais código.

Uma vez que a especificação é carregada, o agente pede ao Claude que a decomponha em uma lista numerada de etapas. O prompt é deliberadamente mínimo — queremos uma lista limpa de etapas, não explicação em prosa.

O analisador é simples: qualquer linha que começa com um dígito é uma etapa. Harnesses de produção frequentemente pedem saída JSON estruturada e analisam isso em vez disso, mas texto simples é mais fácil de inspecionar quando você está colocando o sistema em funcionamento pela primeira vez.

Ponto de Verificação do Módulo

Antes de continuar, preveja: o que response.content[0].text contém após a chamada plan_steps acima? A lista numerada de etapas gerada pelo modelo — não uma contagem de tokens, não o prompt de sistema, não a resposta HTTP bruta. Adicione print(raw) antes da compreensão de lista e execute contra uma especificação real para confirmar.

O agente precisa fazer coisas — ler arquivos, escrever arquivos, executar comandos. No SDK da Anthropic, as ferramentas são definidas como schemas JSON que descrevem o que cada ferramenta aceita. Pense em uma definição de ferramenta como uma descrição de cargo que você entrega a um novo empreiteiro: um nome, o que a função faz e quais informações eles precisam para começar.

Agora adicione a função de despacho que roteia um bloco de chamada de ferramenta para sua implementação real:

Duas ferramentas, uma função de despacho, onze linhas. O módulo 03 mostrou como estender isso incrementalmente — adicionar uma ferramenta run_command segue exatamente o mesmo padrão. Comece com as ferramentas mínimas que a tarefa requer e adicione mais apenas quando tiver evidências de que uma capacidade está faltando.

O loop de execução é onde a tese central do caminho se torna código. Cada etapa recebe o histórico completo de cada etapa concluída antes dela — não um resumo, não uma visão filtrada — para que as decisões do modelo sejam sempre ancoradas no que realmente aconteceu.

Observe que context["history"] cresce com cada chamada. A etapa 3 pode ver as etapas 1 e 2 em pleno detalhe. É isso que torna as saídas coerentes — nenhuma etapa está trabalhando às cegas. Quando nenhum bloco tool_use aparece, a resposta de texto do modelo é tratada como o resultado da etapa e acrescentada ao histórico para que etapas posteriores ainda a vejam.

Ponto de Verificação Reflexivo

O que quebraria se você executasse todas as etapas em paralelo em vez de sequencialmente?

Cada etapa começaria com um histórico vazio. A etapa 3 não poderia saber que a etapa 1 já criou o arquivo que ela deveria ler. As etapas entrariam em conflito ou duplicariam trabalho, e o relatório final seria incoerente — exatamente o modo de falha que o módulo 06 descreve na armadilha multi-agente. Execução sequencial com contexto compartilhado produz melhor saída, mesmo quando paralelo parece mais rápido no papel.

Quando todas as etapas terminam, o agente pede ao Claude que transforme o histórico acumulado em um relatório de status legível por humanos, depois o escreve no disco.

O relatório resume o que o agente realmente fez, não o que planejou fazer. Se a etapa 2 falhou em encontrar um arquivo, o histórico capturou essa falha e o relatório reflete a realidade. Essa trilha de auditoria honesta é o que torna o sistema confiável o suficiente para usar em trabalho real.

Agora monte os quatro estágios em uma única função run_task_agent. Cada estágio chama uma função que você já viu — sem nova lógica, apenas composição em ordem.

Este é o agente completo. Quatro estágios, seis funções, uma passagem linear pela especificação. O harness do SDLC que rodo no meu Mac Mini segue exatamente essa forma — a versão de produção adiciona um wrapper de retry em torno de execute_step e escreve logs estruturados, mas o loop central é idêntico.

Como Isso se Conecta ao Módulo 06

O módulo 06 explicará por que essa arquitetura é confiável: o princípio da corrida de revezamento (cada etapa passa o bastão — o contexto completo — para o próximo corredor), e por que sistemas multi-agentes falham quando essa passagem é quebrada. O que você construiu aqui é a demonstração prática da teoria.

O exercício abaixo estende o capstone com um gate de confirmação humana antes de o relatório ser escrito — o mesmo padrão de checkpoint do módulo 04, aplicado no momento exato em que um erro seria mais difícil de desfazer.