# Modelo, Harness e Agent: como funciona um agente de IA? Entenda o papel do modelo, do harness e do contexto em um agente de IA, acompanhando uma correção de código do pedido inicial até os testes. Por Bruno Rana Publicado em: 2026-10-27 Atualizado em: 2026-11-04 Artigo original: https://buildrun.com.br/blog/harness-modelo-agente/ ![Sketch do ciclo de um agente: o modelo propõe, o harness executa uma operação, o resultado atualiza o contexto e uma nova decisão continua o trabalho ou para ao atingir a meta ou um limite.](https://buildrun.com.br/diagrams/harness-workshop-loop.webp) O modelo propõe; o harness executa a operação permitida, devolve o resultado ao contexto e aplica as condições de parada. 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](https://developers.openai.com/blog/codex-as-a-platform) 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](https://www.anthropic.com/research/effective-harnesses-for-long-running-agents), 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.
Uma bandeja de contexto alimenta o modelo, enquanto os pesos aparecem separados numa caixa.
O contexto reúne informações usadas nesta chamada; ele não é o conjunto de pesos do 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](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents) 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.
Um teste que falhou leva à correção de código e à execução de novos testes.
Observar o resultado guia a próxima decisão; a execução do ciclo não implica publicação.
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: ```text 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](https://openai.com/index/harness-engineering/) 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](https://buildrun.com.br/blog/o-que-e-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](https://buildrun.com.br/blog/o-que-e-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](https://buildrun.com.br/blog/rag-envia-documentos-para-ia/) é 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](https://buildrun.com.br/blog/formacao-buildrun/), 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](https://developers.openai.com/blog/codex-as-a-platform) * [Effective harnesses for long-running agents — Anthropic](https://www.anthropic.com/research/effective-harnesses-for-long-running-agents) * [Effective context engineering for AI agents — Anthropic](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents) * [Harness engineering — OpenAI](https://openai.com/index/harness-engineering/)