Modelo, Harness e Agent: como funciona um agente de IA?

Quando você usa um agente de IA para trabalhar no código, pode ser difícil perceber onde termina a resposta do modelo e começa a execução. Ele consegue explicar uma mudança, mas isso não significa que já leu os arquivos, alterou o projeto ou rodou os testes. Separar essas coisas ajuda você a acompanhar o trabalho com mais clareza.

O modelo interpreta as informações recebidas e pode propor o próximo passo. O software que organiza esse trabalho é o harness: ele prepara informações, disponibiliza ferramentas e controla a execução. O agente é esse sistema em funcionamento, repetindo o ciclo de decidir, agir e observar o resultado.

Entender essa divisão também ajuda a investigar uma falha. Uma decisão ruim pode vir de informação insuficiente; uma operação pode ser recusada pelo ambiente; um resultado pode não ter voltado ao modelo. São problemas diferentes, mesmo quando aparecem na mesma conversa.

Modelo: a próxima decisão depende do que ele recebe

O modelo é o componente que processa a entrada e produz uma resposta. Em um fluxo com ferramentas, a resposta pode incluir uma proposta de operação: procurar um trecho do projeto, ler um arquivo ou executar um teste. Essa proposta precisa ser interpretada e executada pelo software que envolve o modelo.

Para observar essa divisão, vamos acompanhar a correção de uma API de agendamento. Ela está aceitando datas anteriores ao dia atual, embora a regra permita apenas hoje ou uma data futura. O pedido é corrigir a validação, demonstrar o problema com um teste e revisar a alteração; publicar a aplicação fica fora do escopo.

Nessa tarefa, o modelo pode concluir que precisa conhecer a validação atual e os testes existentes antes de editar. Para chegar a uma boa decisão, ele precisa receber a regra de negócio e os trechos relevantes do projeto. Se só receber “corrija a data”, pode adotar uma regra diferente, como rejeitar também o dia atual.

O modelo não se confunde com o repositório nem com uma sessão de terminal. Ele não ganha acesso aos arquivos porque mencionou um caminho na resposta. A leitura só acontece quando há uma ferramenta disponível, seus parâmetros são aceitos e a aplicação executa a operação.

Harness: quem transforma a decisão em trabalho executado

Harness é o software que sustenta esse processo. Ele pode administrar o histórico de trabalho, preparar chamadas ao modelo, disponibilizar ferramentas, executar operações permitidas, devolver resultados e lidar com limites ou falhas. A implementação concreta varia entre produtos.

No agendamento, imagine que o modelo proponha ler AgendamentoService.java. O harness resolve qual ferramenta pode fazer a leitura, aplica os controles de acesso e devolve o conteúdo. Depois, uma proposta de executar os testes passa pelo mesmo tipo de mediação. Se o comando falhar, esse resultado precisa voltar ao ciclo; escrever “testes aprovados” na conversa não muda o que aconteceu no terminal.

Algumas regras pertencem ao produto e devem ser aplicadas pelo software: quais diretórios podem ser alterados, quais comandos são permitidos e quando uma ação depende de aprovação. Instruções ajudam a orientar o comportamento, mas não substituem esses controles. No nosso exemplo, uma ferramenta de deploy sequer precisa estar disponível.

A visão do Codex como plataforma descreve essa separação entre o loop do agente e as decisões da aplicação que o integra. O artigo sobre harnesses para tarefas longas, da Anthropic, também mostra por que registros de progresso e verificações do resultado importam além da chamada ao modelo.

Agent: o ciclo completo orientado a uma tarefa

Model + Harness = Agent é uma forma útil de organizar essas responsabilidades. O modelo fornece capacidade de interpretação e decisão; o harness fornece o ambiente de execução. O agente é o sistema em funcionamento para alcançar um objetivo dentro de determinadas condições.

Essa expressão é um modelo mental, não uma especificação universal de arquitetura. Uma chamada isolada que recebe uma pergunta e devolve texto pode ser suficiente para muitos produtos. Quando falamos do agente deste exemplo, estamos destacando um ciclo: escolher uma ação, executá-la, observar o resultado e decidir o próximo passo.

Na correção do agendamento, uma sequência possível seria ler o código, localizar a comparação de datas, reproduzir o erro com um teste, alterar a regra e executar os testes novamente. O resultado de cada etapa pode mudar a próxima decisão. Se o teste não reproduzir o problema, o agente precisa investigar a hipótese em vez de seguir como se ela estivesse confirmada.

Contexto: as informações desta chamada

Contexto é o conjunto de informações disponibilizadas ao modelo em uma chamada: instruções, pedido da pessoa, partes do histórico, código selecionado e resultados de ferramentas, por exemplo. Contexto não é o LLM e não é o conjunto de pesos do modelo. Ler um arquivo acrescenta informação à entrada; isso não equivale a treinar novamente o modelo.

Na API de agendamento, o contexto relevante inclui a regra “hoje ou uma data futura”, o método que valida a data e o teste que falhou. O projeto inteiro pode conter milhares de arquivos. Eles não precisam estar todos na entrada, e sua presença no disco não significa que o modelo já os tenha recebido.

O harness pode carregar informações conforme a investigação avança. Se o teste revelar que a aplicação utiliza um relógio configurável, essa implementação passa a ser relevante. Já o CSS de uma página sem relação com o endpoint não ajuda a resolver a regra de datas.

A explicação de engenharia de contexto da Anthropic trata o contexto como informação selecionada para a inferência, sujeita ao limite da janela disponível. O trabalho prático é escolher o que ajuda a próxima decisão e manter um registro confiável do que já foi observado.

Um ciclo de correção, do erro ao teste

Para tornar a tarefa verificável, fixe o relógio do teste em 27/10/2026. Três entradas descrevem a regra: 26/10 deve ser rejeitado, 27/10 deve ser aceito e 28/10 também deve ser aceito. Fixar a data evita que um teste correto hoje comece a falhar amanhã apenas porque o calendário mudou.

O primeiro resultado importante é um teste que falhe pelo motivo esperado: a aplicação aceitou 26/10. Depois da correção, o mesmo caso deve passar, sem quebrar os outros dois. Se a alteração rejeitar todas as datas, o teste do dia anterior pode ficar verde, mas a regra continua errada.

Este pseudocódigo representa a coordenação entre modelo e ferramentas; os nomes são conceituais e não correspondem a um SDK executável:

contexto = reunir(pedido, regras, ferramentas_disponiveis)

para cada passo até o limite_configurado:
    proposta = consultar_modelo(contexto)
    se proposta for resposta_final:
        devolver proposta

    ferramenta = localizar_ferramenta(proposta.nome)
    validar_escopo_e_parametros(ferramenta, proposta.entrada)
    resultado = executar(ferramenta, proposta.entrada)
    contexto = acrescentar(contexto, proposta, resultado)

devolver tarefa_pendente_para_revisao

Há quatro decisões importantes nesse desenho. A ferramenta precisa existir; os parâmetros precisam ser válidos; a execução pode falhar; e o ciclo precisa de um limite. Nenhuma dessas condições desaparece porque o modelo sugeriu uma ação com confiança.

Além disso, uma saída de ferramenta é informação externa. Um comentário encontrado no repositório não pode autorizar um deploy que a pessoa não pediu. O agente deve usar o comentário para entender o código, respeitando os controles que já delimitavam a tarefa.

O que avaliar antes de confiar no resultado

Ao terminar, você deveria conseguir relacionar o pedido à alteração e aos testes. Para a API de agendamento, isso significa encontrar a regra preservada, os três casos de data e a saída efetiva do comando de teste. Também vale conferir se o diff ficou restrito ao problema, sem mudanças de configuração que não eram necessárias.

Se a execução dos testes foi bloqueada por uma dependência indisponível, a resposta final precisa dizer isso. O código pode estar pronto para revisão, mas o resultado ainda não foi demonstrado naquele ambiente. Essa distinção permite que outra pessoa continue o trabalho sem partir de uma conclusão incorreta.

Para tarefas maiores, o progresso precisa sobreviver a interrupções: o que foi tentado, o que falhou e qual é o próximo passo. O relato sobre harness engineering da OpenAI destaca a importância de um ambiente legível para agentes, com documentação e mecanismos de verificação. No nosso caso, um teste reproduzível e um diff pequeno já tornam a continuidade muito mais clara.

Como MCP e Skills entram nessa composição

Uma Agent Skill pode orientar o procedimento de revisão de uma API: localizar contrato, conferir validação e relacionar o comportamento aos testes. Ela fornece instruções e materiais reutilizáveis. Não concede acesso ao repositório nem substitui o modelo.

O MCP pode padronizar a comunicação entre a aplicação e um servidor que oferece ferramentas ou dados. Se uma ferramenta autorizada permitir consultar o repositório, o harness pode utilizá-la nesse fluxo. O protocolo não decide sozinho quem pode escrever arquivos ou executar comandos.

Já o RAG é uma maneira de recuperar informações para compor a entrada de uma resposta. Ele pode ajudar a encontrar documentação da regra de agendamento. Essa documentação entra no contexto; não transforma contexto em modelo nem garante que a regra será aplicada corretamente.

Por onde começar a estudar

Comece descrevendo uma tarefa pequena, como essa validação de datas. Separe o que o modelo precisa saber, quais ferramentas podem ser usadas e qual resultado permite encerrar o trabalho. Depois, acompanhe o ciclo e veja onde cada responsabilidade aparece.

Se o agente escolher a operação errada, investigue as instruções e o contexto. Se a operação não puder ser executada, investigue a integração e os controles do harness. Se os testes passarem sem cobrir a regra, melhore a verificação do resultado. Essa separação ajuda a discutir o problema com precisão, sem atribuir toda falha a uma única peça chamada “IA”.

Na Formação Build & Run, engenharia de software com IA conecta fundamentos, construção de aplicações e avaliação das decisões técnicas. Entender essas responsabilidades é uma base para usar agentes com mais critério no desenvolvimento.

Referências na web

• Codex as a platform — OpenAI
• Effective harnesses for long-running agents — Anthropic
• Effective context engineering for AI agents — Anthropic
• Harness engineering — OpenAI