O loop do agente e as ferramentas

Aula 5

O loop básico: reunir contexto, agir, verificar, repetir

Ao apresentar o Claude Agent SDK (antes chamado Claude Code SDK), a Anthropic descreve o loop de qualquer agente em três fases que se repetem até a tarefa terminar: reunir contexto, agir e verificar o trabalho. O princípio de design por trás do SDK é "dar um computador ao agente": terminal, sistema de arquivos e bash, as mesmas ferramentas que um desenvolvedor usa.

• Reunir contexto: busca agêntica primeiro (grep, leitura de arquivos, listagem de diretórios), busca semântica só se for necessária, subagentes com janelas de contexto isoladas e compactação automática quando a janela se aproxima do limite.
• Agir: ferramentas próprias, scripts em bash, geração de código e servidores MCP para integrações externas.
• Verificar: regras determinísticas como lint e checagem de tipos, feedback visual por screenshots e, por último, um LLM como juiz, que o artigo considera menos robusto e mais lento.

Em código, o loop é surpreendentemente pequeno. A complexidade de um harness não está no laço em si, mas em tudo o que decide o que entra em cada chamada e o que acontece com cada resultado:

mensagens = [system_prompt, tarefa_do_usuario]
while True:
    resposta = modelo(mensagens, ferramentas)
    if resposta.tipo == "texto_final":
        break                        # o modelo decidiu parar
    for chamada in resposta.chamadas_de_ferramenta:
        if not permitido(chamada):   # política do harness
            resultado = "negado pela política"
        else:
            resultado = executar(chamada)
        mensagens.append(resultado)  # o resultado volta ao contexto
    mensagens = compactar_se_preciso(mensagens)

O artigo Building effective agents acrescenta uma recomendação de segurança que todo loop precisa: uma condição de parada explícita, como um número máximo de iterações, e testes extensivos em ambiente isolado antes de dar autonomia real.

Fontes desta aula: Anthropic: Building agents with the Claude Agent SDK · Anthropic: Building effective agents

Aula 6

Projetando ferramentas para agentes

Uma ferramenta é um contrato entre um sistema determinístico (seu código) e um sistema não determinístico (o modelo). A Anthropic insiste que ferramentas devem ser desenhadas para agentes, não como se desenharia uma API para outro desenvolvedor. No apêndice de Building effective agents, o time conta que, ao otimizar o agente para o benchmark SWE-bench, gastou mais tempo ajustando ferramentas do que ajustando o prompt geral. Um exemplo: exigir caminhos de arquivo absolutos eliminou uma classe inteira de erros com caminhos relativos.

O artigo Writing effective tools for AI agents organiza as boas práticas:

• Escolha ferramentas pelo trabalho, não pela API. search_contacts é melhor que list_contacts. Uma ferramenta schedule_event pode substituir três chamadas (listar usuários, listar eventos e criar evento).
• Use namespaces. Prefixos por serviço e recurso, como asana_search e jira_users_search, reduzem confusão quando há muitas ferramentas.
• Devolva contexto útil. Nomes legíveis em vez de UUIDs, e um parâmetro de formato que permite resposta concisa ou detalhada.
• Economize tokens. Paginação, filtros e truncamento. O Claude Code limita respostas de ferramentas a 25 mil tokens por padrão.
• Escreva erros que ensinam. Uma mensagem de erro deve dizer o que corrigir, não só que algo falhou.
• Trate a descrição como prompt. Renomear um parâmetro ambíguo de user para user_id muda o comportamento do modelo.

O artigo também propõe um método: prototipar as ferramentas, escrever avaliações com tarefas realistas que exigem várias chamadas, medir tempo, número de chamadas, tokens e erros, e então pedir ao próprio agente que reescreva as descrições com base nas falhas observadas, sempre validando em um conjunto de teste separado. Em um caso relatado no estudo do sistema de pesquisa multiagente, um agente que reescreveu descrições ruins de ferramentas reduziu em 40% o tempo de conclusão de tarefas futuras.

Fontes desta aula: Anthropic: Writing effective tools for AI agents · Anthropic: Building effective agents · Anthropic: How we built our multi-agent research system

Aula 7

MCP e o custo de ter ferramentas demais

O Model Context Protocol (MCP) é um padrão aberto para conectar aplicações de IA a fontes de dados e ferramentas. A documentação oficial o compara a uma porta USB-C: em vez de escrever uma integração para cada par de agente e serviço, cada serviço publica um servidor MCP e qualquer cliente compatível passa a usá-lo. No estudo de onze harnesses de produção, oito suportam MCP.

A facilidade de adicionar servidores cria um risco que a HumanLayer descreve bem: ferramentas demais ocupam contexto. Cada ferramenta conectada traz nome, descrição e esquema de parâmetros para dentro da janela de contexto, mesmo quando não é usada. Dez servidores com dez ferramentas cada podem consumir milhares de tokens antes de o agente ler a primeira linha da tarefa, e ainda aumentam a chance de o modelo escolher a ferramenta errada. A Anthropic recomenda conjuntos mínimos e sem sobreposição: se um engenheiro humano não consegue dizer com certeza qual ferramenta usar, o modelo também não consegue.

Três estratégias controlam esse custo:

• Conectar servidores MCP por projeto, e não globalmente, mantendo só os que a tarefa usa.
• Preferir a linha de comando quando ela já existe: o agente sabe usar git, gh ou psql sem descrições extras no contexto.
• Empacotar conhecimento especializado como skills, que só carregam o conteúdo completo quando são relevantes (assunto do módulo 3).

Fontes desta aula: Anthropic: Writing effective tools for AI agents · HumanLayer: Skill Issue · Barbaste et al.: Harness Engineering (arXiv)

Aula 8

Hooks e middleware: interceptar cada passo

Um harness maduro não deixa o loop correr solto. Ele intercepta pontos específicos: antes de chamar o modelo, depois da resposta, antes de executar uma ferramenta e depois do resultado. A LangChain chama esses pontos de middleware. O Claude Code e o Agent SDK chamam de hooks. A ideia é a mesma: código determinístico que roda em momentos definidos do loop.

A diferença entre um hook e uma instrução em AGENTS.md é central para todo o curso. A documentação de boas práticas do Claude Code resume assim: o arquivo de instruções é consultivo, o hook é determinístico. Se uma regra precisa valer sempre (rodar o formatador depois de cada edição, nunca escrever em .env), ela deve virar hook. O Claude Code oferece inclusive um hook de parada que impede o agente de encerrar o turno até uma checagem passar, com um limite de segurança de oito bloqueios seguidos.

A HumanLayer acrescenta uma regra de ouro para hooks de verificação: silenciosos no sucesso e detalhados na falha. Um hook que imprime cem linhas quando tudo deu certo desperdiça contexto. Um hook que, na falha, diz exatamente o arquivo, a linha e o que corrigir vira um sensor de alta qualidade, tema do módulo 6.

Fontes desta aula: Sydney Runkle: How to Build a Custom Agent Harness · HumanLayer: Skill Issue · Claude Code: Best practices

Erros comuns

• Expor a API inteira como ferramentas. Trinta endpoints viram trinta ferramentas e o modelo se perde. Agrupe por tarefa.
• Devolver JSON cru e enorme. Respostas grandes enchem o contexto e escondem o que importa. Filtre e pagine.
• Mensagens de erro genéricas. "Erro 400" não ensina nada. Diga qual parâmetro está errado e qual é o formato esperado.
• Confiar no prompt para regras obrigatórias. Se a regra não pode falhar, transforme em hook ou em permissão.
• Loop sem condição de parada. Defina limite de iterações, de custo e de tempo.

Aplicação prática

1. Liste as ferramentas e servidores MCP ativos no seu agente e remova os que não foram usados na última semana.
2. Escolha uma ferramenta própria e reescreva a descrição como se explicasse a um colega novo: quando usar, quando não usar, formato dos parâmetros e um exemplo.
3. Adicione um hook que rode o formatador e o lint depois de cada edição, imprimindo saída só quando houver erro.
4. Escreva cinco tarefas realistas e meça quantas chamadas de ferramenta o agente faz em cada uma antes e depois das mudanças.

Siglas usadas neste módulo

MCP:

Model Context Protocol, protocolo aberto para conectar agentes a ferramentas e dados.

SDK:

Software Development Kit, kit de desenvolvimento de software.

API:

Application Programming Interface, interface de programação de aplicações.

UUID:

Universally Unique Identifier, identificador único universal.

JSON:

JavaScript Object Notation, formato de dados em texto.

LLM:

Large Language Model, modelo de linguagem de grande escala.