{"content_id":"tx8xp2gpig","slug":"ai-agent-harness-loop-graph-engineering","locale":"pt","schema_type":"TechArticle","category":"knowledge_base","category_name":"Base de Conhecimento","title":"Entendendo, em ordem, a engenharia de harness, loop e grafo dos agentes de IA","summary":"O harness projeta o ambiente de trabalho e os mecanismos de controle do agente; o loop, as regras de repetição e encerramento; e o grafo, os estados permitidos e as rotas de transição. É mais correto entender os três termos como perspectivas práticas para lidar com a autonomia e os riscos dos agentes de IA do que como uma classificação oficialmente padronizada.","sponsorship_disclosure":null,"author":{"name":"injoys","url":"https://injoys.com/ko/about"},"key_points":["A engenharia de harness consiste em projetar o contexto, as ferramentas, as permissões, a validação, os logs e os procedimentos de aprovação externos ao modelo como um único ambiente de execução.","A engenharia de loop define as condições, o orçamento e os critérios de encerramento para que o agente repita o ciclo de planejamento, execução, validação e correção.","A engenharia de grafo usa estados e regras de transição para limitar ou ajustar explicitamente as rotas que o agente pode escolher.","Para a maioria das organizações, é mais eficiente aprimorar primeiro o harness e a estrutura de avaliação de um único agente do que adotar um grafo complexo com múltiplos agentes.","Aprovar apenas um relatório resumido produzido por IA não é suficiente para códigos de alto risco; também é necessário verificar os testes, o escopo das alterações, os limites de segurança e os resultados originais."],"content_markdown":"À medida que os agentes de IA passaram a assumir tarefas de longa duração, tornou-se difícil obter resultados estáveis apenas escrevendo bons prompts. Isso ocorre porque também é necessário projetar quais informações o agente verá, quais ferramentas usará, quando repetirá uma ação, por quais caminhos seguirá e em quais pontos deverá obter aprovação humana.\n\nAo explicar esse problema, aparecem com frequência as expressões **engenharia de harness**, **engenharia de loops** e **engenharia de grafos**. Elas não são padrões internacionais nem classificações acadêmicas rigorosamente consensuais. Há sobreposição entre elas, e seus significados podem variar de acordo com o produto e a equipe de desenvolvimento. Portanto, em vez de memorizá-las como termos da moda de cada ano, é mais útil distingui-las pelas perguntas de controle às quais cada uma busca responder.\n\n## Comparação dos três conceitos em uma visão geral\n\n| Conceito | Pergunta central | Principal objeto de projeto | Mecanismos típicos de prevenção de falhas |\n|---|---|---|---|\n| Engenharia de harness | Em qual ambiente e sob quais regras o agente trabalha? | Contexto, ferramentas, permissões, sandbox, hooks, logs, aprovações, avaliações | Privilégio mínimo, aprovação de comandos perigosos, execução de testes, seleção de contexto |\n| Engenharia de loops | O que deve ser repetido e quando deve parar? | Ciclos de planejamento, execução e verificação, processamento de eventos, novas tentativas, orçamento, condições de encerramento | Número máximo de repetições, limites de tempo e tokens, avaliação de progresso, encaminhamento em caso de falha |\n| Engenharia de grafos | Quais estados e caminhos são permitidos? | Nós, estados, transições, ramificações, processamento paralelo, checkpoints | Transições proibidas, validação de estado, nós de aprovação, caminhos de recuperação |\n\nEm resumo, **o harness define o ambiente e os limites**, **o loop define as regras de repetição** e **o grafo define a estrutura dos caminhos possíveis**. Em sistemas reais, pode haver um loop dentro de um nó do grafo, enquanto o grafo inteiro é executado dentro de um único harness.\n\n## Como os métodos de controle de agentes evoluíram\n\n### Agentes iniciais: workflows predefinidos complementavam a autonomia\n\nOs primeiros agentes de IA generativa frequentemente esqueciam seus objetivos em tarefas longas, repetiam chamadas incorretas de ferramentas ou produziam resultados sem fundamento. Por isso, os desenvolvedores dividiam tarefas grandes em etapas menores e fixavam as entradas e saídas de cada etapa.\n\nNessa abordagem, uma pessoa descreve todo o processo como uma cadeia, um fluxograma ou uma máquina de estados, enquanto o LLM assume tarefas limitadas, como classificação, extração, resumo e elaboração de rascunhos. Frameworks como LangGraph são usados para representar ramificações, ciclos, checkpoints e intervenção humana mantendo o estado.\n\nNo entanto, a orquestração baseada em grafos não é uma abordagem ultrapassada que terminou em determinado ano. Ainda hoje, grafos explícitos são adequados para trabalhos em que auditabilidade, reprodutibilidade, conformidade regulatória ou procedimentos precisos de recuperação são importantes.\n\n### Melhoria do desempenho dos modelos: de caminhos fixos ao uso dinâmico de ferramentas\n\nCom o avanço da capacidade de raciocínio e de uso de ferramentas, um único agente passou a poder escolher ações como pesquisar, editar código, executar testes e ler arquivos de acordo com a situação. As abordagens da família ReAct são uma estrutura representativa que alterna raciocínio, ação e observação.\n\nEssa mudança reduziu a necessidade de uma pessoa definir previamente todas as ramificações. Por outro lado, tornou mais importante gerenciar as informações lidas pelo agente, as permissões que ele possui, o custo de execução e os métodos de recuperação de erros. É nesse contexto que a engenharia de contexto e a engenharia de harness passam a ocupar o centro da prática.\n\n### Tarefas longas e múltiplos agentes: a recombinação de loops e grafos\n\nEm tarefas longas, ciclos repetidos de planejamento, execução e verificação são mais importantes do que uma única chamada ao modelo. Quando vários agentes participam, também é necessário especificar papéis, formatos dos entregáveis, permissões e condições de encerramento. Ao mesmo tempo, deixar loops autônomos completamente sem supervisão pode causar explosão de custos, novas tentativas infinitas, hacking de recompensa e otimização de objetivos incorretos.\n\nPor isso, os sistemas modernos de agentes são projetados para **combinar trechos em que a autonomia é permitida com trechos controlados de forma determinística**, em vez de eliminar a autonomia. Isso não é um simples retorno às antigas cadeias fixas, mas uma forma de cercar a execução flexível com estados, transições e políticas.\n\nEssa mudança representa mais uma alteração de ênfase no projeto do que uma cronologia exata. Grafos, loops e harnesses coexistem desde o início e continuam sendo usados em conjunto.\n\n## O que a engenharia de harness abrange\n\nO harness não é o modelo-base em si, mas **o sistema de execução que envolve o modelo para que ele realize o trabalho de fato**. Mesmo usando o mesmo modelo, a taxa de sucesso, o custo, a segurança e a reprodutibilidade podem variar muito conforme o harness.\n\n### Principais componentes de um harness\n\n1. **Sistema de instruções**: diretrizes do sistema, regras do repositório, padrões de código, prioridades e ações proibidas\n2. **Fornecimento de contexto**: pesquisa, seleção de arquivos, resumo, memória e inserção de documentos no momento necessário\n3. **Interfaces de ferramentas**: edição de arquivos, terminal, navegador, banco de dados e APIs externas\n4. **Permissões e isolamento**: escopo de leitura e gravação, acesso a informações secretas, restrições de rede e sandbox\n5. **Mecanismos de verificação**: testes, linters, verificação de tipos, validação de schemas e checagem de fatos\n6. **Aprovação humana**: aprovação de ações difíceis de reverter, como implantação, pagamento, exclusão e envio externo\n7. **Observabilidade**: registros de chamadas, custos, latência, erros, histórico de alterações e fundamentos das decisões\n8. **Políticas de recuperação**: novas tentativas, restauração do estado anterior, interrupção da tarefa e encaminhamento ao responsável\n\nArquivos de instruções de projeto ou hooks do Claude Code podem ser vistos como exemplos de componentes de um harness. No entanto, uma funcionalidade específica de um produto não representa todo o harness.\n\n### Diferença em relação à engenharia de contexto\n\nA engenharia de contexto otimiza quais informações e instruções devem ser incluídas na chamada atual ao modelo. Isso inclui recuperar apenas documentos relevantes por meio de pesquisa, resumir conversas antigas, salvar o estado da tarefa em arquivos externos e separar o contexto por subtarefa.\n\nA engenharia de harness é mais ampla. Além do contexto, ela abrange permissões de ferramentas, ambiente de execução, aprovações, verificações, logging e limites de custo. Portanto, a engenharia de contexto é uma parte central do harness, mas é impreciso usar os dois termos como se tivessem exatamente o mesmo significado.\n\n## O essencial na engenharia de loops são as condições de encerramento\n\nUm loop faz com que o agente verifique o resultado depois de produzi-lo e tente novamente caso seja insuficiente. O importante não é a repetição em si, mas **a definição de progresso e as condições de interrupção**.\n\n### Tipos representativos de loops\n\n- **Loop de verificação**: após criar um rascunho, verifica-o com testes ou critérios de avaliação e corrige os itens que falharam.\n- **Loop orientado a eventos**: inicia uma tarefa quando ocorre um evento externo, como um e-mail, uma notificação, uma alteração de código ou dados de sensores.\n- **Loop de exploração**: investiga várias hipóteses ou fontes e ajusta o escopo da busca até obter evidências suficientes.\n- **Loop de melhoria**: escolhe a próxima estratégia com base no resultado anterior e nos valores de avaliação. Como otimizar apenas uma pontuação pode causar hacking de recompensa, são necessários vários critérios de avaliação e revisão humana.\n- **Loop de recuperação**: classifica a causa do erro, faz novas tentativas dentro do escopo permitido e encaminha a tarefa a uma pessoa caso o problema não seja resolvido.\n\n### Contratos necessários para loops seguros\n\nUm contrato entre agentes não é um contrato jurídico, mas uma especificação de execução que define entradas, saídas e responsabilidades. É recomendável incluir os seguintes itens.\n\n| Item do contrato | O que especificar |\n|---|---|\n| Objetivo | Resultado que deve ser concluído e itens fora do escopo |\n| Entrada | Dados que podem ser usados, atualidade e nível de confiança |\n| Saída | Schema JSON, formato do documento, evidências obrigatórias e resultados de testes |\n| Permissões | Ferramentas permitidas, escopo de arquivos, envio externo e permissões de alteração |\n| Verificação | Testes e critérios de avaliação que devem ser aprovados |\n| Orçamento | Tokens, tempo, número de chamadas e quantidade de tarefas paralelas |\n| Encerramento | Condições de sucesso, ausência de progresso, esgotamento do orçamento e detecção de risco |\n| Encaminhamento | Qual pessoa ou agente assumirá em caso de falha |\n\nSe as condições de conclusão forem ambíguas, o agente poderá considerar que está avançando mesmo enquanto apenas altera frases ou repete a mesma pesquisa. Em vez de estabelecer somente um número máximo de repetições, é melhor considerar em conjunto a qualidade do resultado, o aumento de novas informações, a evolução dos erros e o custo.\n\n## A engenharia de grafos estrutura os limites da autonomia\n\nUm grafo representa o trabalho por meio de nós e conexões. Um nó pode ser uma chamada ao modelo, a execução de uma ferramenta, uma aprovação humana ou um processo de verificação, enquanto as conexões representam a próxima ação de acordo com o estado.\n\n### Diferença entre cadeias e grafos\n\n- **Uma cadeia** é adequada para procedimentos lineares que seguem de A para B e de B para C.\n- **Um grafo** é adequado para tarefas que exigem ramificações condicionais, repetições, execução paralela, recuperação de falhas e salvamento intermediário.\n- **Um grafo dinâmico** permite que o modelo proponha a próxima subtarefa ou o próximo caminho durante a execução.\n- **Um grafo restrito** faz com que o modelo se mova somente entre os nós e as transições permitidos, mesmo quando é ele que faz a escolha.\n\nO objetivo do projeto moderno de grafos não é fazer com que uma pessoa decida previamente todas as ações. Trata-se de inserir na estrutura **condições invariáveis que devem ser respeitadas**, como exigir a passagem por um nó de aprovação antes da exclusão de dados ou impedir a transição de um estado de falha nos testes para o estado de implantação.\n\n### Sinais de que um grafo é necessário\n\nSe várias das condições abaixo se aplicarem, vale a pena considerar um grafo explícito.\n\n- Há um ponto de recuperação claro ao qual se deve retornar após uma falha.\n- Existe uma etapa que exige obrigatoriamente aprovação humana.\n- É necessário executar várias tarefas em paralelo e depois combinar os resultados.\n- As ferramentas ou permissões disponíveis variam de acordo com o estado.\n- É necessário auditar ou reproduzir todo o caminho de execução.\n- Um loop de um único agente repete a mesma falha.\n\nTransformar em grafo até mesmo um simples resumo de documento ou uma única conversão de dados pode apenas aumentar a complexidade.\n\n## Ordem de aplicação prática: começar pelo harness e expandir conforme necessário\n\nPara a maioria das equipes, a ordem a seguir é realista.\n\n1. **Defina uma única tarefa e os critérios de sucesso.** Primeiro, reúna as entradas, as saídas esperadas e os casos de falha.\n2. **Crie um harness mínimo.** Forneça apenas o contexto e as ferramentas necessários e configure permissões, testes, logs e limites de custo.\n3. **Construa um conjunto de avaliação.** Inclua não apenas casos normais, mas também solicitações ambíguas, documentos incorretos, erros de ferramentas e tentativas de exceder permissões.\n4. **Transforme em loops os pontos que exigem repetição.** Permita novas tentativas apenas nos trechos em que a verificação e a correção realmente elevam a qualidade.\n5. **Promova para um grafo quando as ramificações e a recuperação se tornarem complexas.** Especifique estados e transições e coloque nós de aprovação antes de ações arriscadas.\n6. **Use múltiplos agentes apenas quando a separação do trabalho trouxer benefícios.** Se não forem necessárias exploração paralela ou diferentes funções especializadas, um único agente pode ser mais simples e barato.\n\n## Diferenças de aplicação em programação e pesquisa\n\n| Item | Tarefas de programação | Tarefas de pesquisa |\n|---|---|---|\n| Possibilidade de verificação | A verificação automática por testes, build e checagem de tipos é relativamente fácil | É necessário avaliar de forma abrangente a qualidade das fontes, omissões e evidências conflitantes |\n| Valor da exploração dinâmica | Pode ser limitado quando o escopo das alterações está claro | É alto ao comparar diferentes caminhos de pesquisa e hipóteses |\n| Principais riscos | Alterações incorretas, vulnerabilidades de segurança e código ajustado apenas aos testes | Alegações sem fontes, materiais duplicados e viés de confirmação |\n| Controles adequados | Limitação do escopo do repositório, testes, revisão de diff e aprovação de implantação | Registro de fontes, pesquisa independente, busca de evidências contrárias e verificação de citações |\n\nNão se pode afirmar categoricamente que workflows dinâmicos sejam sempre ineficientes para programação e sempre vantajosos para pesquisa. Uma migração de grande escala que possa ser testada pode ser adequada a agentes autônomos, enquanto uma consulta factual com resposta clara pode ser mais eficiente com um procedimento fixo de pesquisa. As variáveis centrais não são a área, mas **a clareza do objetivo, a possibilidade de verificação automática, o espaço de exploração e o custo dos erros**.\n\n## A revisão de código não desaparece; o que muda é a unidade de revisão\n\nQuando agentes escrevem código, os desenvolvedores passam a assumir mais a função de supervisionar requisitos, design, resultados de testes, escopo das alterações e riscos, em vez de digitar diretamente cada linha. Resumos de Pull Requests e relatórios de agentes podem acelerar a revisão.\n\nNo entanto, ler apenas o resumo e aprovar não é uma opção padrão segura. Alterações omitidas pelo agente ou lógicas que ele compreendeu de forma incorreta podem não aparecer nem mesmo no resumo. Nas situações abaixo, é necessário revisar diretamente o diff original e o código relacionado.\n\n- Alterações em autenticação, pagamentos, dados pessoais, criptografia e controle de acesso\n- Alterações no schema do banco de dados ou migrações irreversíveis\n- Código sensível a desempenho e concorrência\n- Refatorações de grande escala fora do escopo dos testes\n- Alterações em dependências externas, configurações de implantação e tratamento de informações secretas\n- Casos em que a explicação do agente não corresponde ao diff real\n\nHuman-in-the-loop não significa que uma pessoa apenas pressione formalmente um botão. Também inclui fornecer evidências das alterações, resultados de testes, possibilidades de falha e procedimentos de reversão para que a pessoa possa tomar uma decisão.\n\n## Armadilhas frequentes\n\n### Múltiplos agentes sem propósito\n\nAumentar o número de agentes gera custos de coordenação de papéis, chamadas duplicadas, transferência de contexto e combinação de resultados. Se não houver necessidade de exploração paralela a partir de diferentes perspectivas nem motivo para separar o contexto, um único agente é melhor.\n\n### Workflows dinâmicos sem limites\n\nPermitir que o agente continue criando subtarefas faz com que o custo de tokens e chamadas de ferramentas aumente rapidamente. O custo é determinado aproximadamente pela soma do custo dos tokens de entrada e saída em cada etapa, do custo das ferramentas, do número de agentes paralelos e da quantidade de repetições. É necessário limitar separadamente o número de chamadas, a quantidade de execuções simultâneas, o orçamento total e o tempo máximo de execução.\n\n### Otimização de uma única métrica de avaliação\n\nSe o único objetivo for a taxa de aprovação nos testes, podem surgir otimizações incorretas, como enfraquecer os testes ou ocultar o tratamento de exceções. É necessário usar em conjunto qualidade, segurança, volume de alterações, custo, latência e avaliação humana.\n\n### Confundir inserção de documentos com fine-tuning\n\nOs resultados podem mudar de forma persistente por meio da pesquisa de documentos ou das instruções do projeto, mas os pesos do modelo não são alterados. Em sentido amplo, isso pode ser descrito como um efeito de aprendizagem do sistema, mas, rigorosamente, trata-se de adaptação por meio de memória externa e contexto. Os documentos ou o índice de pesquisa precisam ser preservados para que as mudanças sejam mantidas nas execuções seguintes.\n\n## Avaliação, segurança e viabilidade econômica frequentemente negligenciadas na operação\n\nO projeto de agentes não termina no diagrama de arquitetura. Na operação real, é importante ter **um sistema que meça o que realmente aconteceu, e não apenas o que foi permitido**.\n\n### Métricas operacionais mínimas\n\n- Taxa de sucesso das tarefas e taxa de correções humanas\n- Custo de modelos e ferramentas por tarefa e tempo total de execução\n- Número de repetições e proporção de chamadas consumidas sem progresso\n- Número de solicitações de aprovação, recusas e tentativas de exceder permissões\n- Chamadas incorretas de ferramentas e taxa de sucesso da recuperação\n- Proporção de resultados enviados sem fontes ou testes\n- Grau de variação dos resultados para a mesma entrada\n\n### Condições invariáveis necessárias para a segurança\n\n- As instruções de documentos externos não têm prioridade superior à política do sistema.\n- Informações secretas não são expostas desnecessariamente na entrada do modelo nem nos logs.\n- As permissões de leitura são separadas das permissões de gravação, exclusão e implantação.\n- Envios externos e ações irreversíveis exigem aprovação separada ou verificação por políticas.\n- O agente não pode modificar arbitrariamente seus próprios critérios de avaliação, testes ou logs de auditoria.\n\nÉ mais seguro impor essas condições invariáveis por meio de sandbox, controle de acesso, transições de grafo e verificadores independentes do que por uma única frase no prompt. A gestão de riscos da IA generativa deve abranger não apenas a precisão do modelo, mas também o ambiente operacional, a supervisão humana e a resposta a incidentes.\n\n## Qual conceito deve ser aprendido primeiro\n\nNa prática atual, o primeiro conceito a dominar é a engenharia de harness. Um contexto preciso, privilégio mínimo, verificação automática, logs, aprovações e limites de custo podem reduzir muitas falhas de um único agente.\n\nEm seguida, adicione loops com condições de encerramento às tarefas em que a repetição melhora a qualidade. Quando as ramificações, o processamento paralelo, a recuperação e os procedimentos de aprovação se tornarem complexos, represente-os explicitamente com grafos. Antes de adotar termos complexos, a prioridade é tornar mensuráveis os objetivos, as permissões, as evidências, os custos e as condições de interrupção do agente.","content_html":"\u003cp\u003eÀ medida que os agentes de IA passaram a assumir tarefas de longa duração, tornou-se difícil obter resultados estáveis apenas escrevendo bons prompts. Isso ocorre porque também é necessário projetar quais informações o agente verá, quais ferramentas usará, quando repetirá uma ação, por quais caminhos seguirá e em quais pontos deverá obter aprovação humana.\u003c/p\u003e\n\u003cp\u003eAo explicar esse problema, aparecem com frequência as expressões \u003cstrong\u003eengenharia de harness\u003c/strong\u003e, \u003cstrong\u003eengenharia de loops\u003c/strong\u003e e \u003cstrong\u003eengenharia de grafos\u003c/strong\u003e. Elas não são padrões internacionais nem classificações acadêmicas rigorosamente consensuais. Há sobreposição entre elas, e seus significados podem variar de acordo com o produto e a equipe de desenvolvimento. Portanto, em vez de memorizá-las como termos da moda de cada ano, é mais útil distingui-las pelas perguntas de controle às quais cada uma busca responder.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#compara%C3%A7%C3%A3o-dos-tr%C3%AAs-conceitos-em-uma-vis%C3%A3o-geral\" class=\"anchor\" id=\"comparação-dos-três-conceitos-em-uma-visão-geral\"\u003e\u003c/a\u003eComparação dos três conceitos em uma visão geral\u003c/h2\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eConceito\u003c/th\u003e\n\u003cth\u003ePergunta central\u003c/th\u003e\n\u003cth\u003ePrincipal objeto de projeto\u003c/th\u003e\n\u003cth\u003eMecanismos típicos de prevenção de falhas\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Conceito\"\u003eEngenharia de harness\u003c/td\u003e\n\u003ctd data-label=\"Pergunta central\"\u003eEm qual ambiente e sob quais regras o agente trabalha?\u003c/td\u003e\n\u003ctd data-label=\"Principal objeto de projeto\"\u003eContexto, ferramentas, permissões, sandbox, hooks, logs, aprovações, avaliações\u003c/td\u003e\n\u003ctd data-label=\"Mecanismos típicos de prevenção de falhas\"\u003ePrivilégio mínimo, aprovação de comandos perigosos, execução de testes, seleção de contexto\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Conceito\"\u003eEngenharia de loops\u003c/td\u003e\n\u003ctd data-label=\"Pergunta central\"\u003eO que deve ser repetido e quando deve parar?\u003c/td\u003e\n\u003ctd data-label=\"Principal objeto de projeto\"\u003eCiclos de planejamento, execução e verificação, processamento de eventos, novas tentativas, orçamento, condições de encerramento\u003c/td\u003e\n\u003ctd data-label=\"Mecanismos típicos de prevenção de falhas\"\u003eNúmero máximo de repetições, limites de tempo e tokens, avaliação de progresso, encaminhamento em caso de falha\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Conceito\"\u003eEngenharia de grafos\u003c/td\u003e\n\u003ctd data-label=\"Pergunta central\"\u003eQuais estados e caminhos são permitidos?\u003c/td\u003e\n\u003ctd data-label=\"Principal objeto de projeto\"\u003eNós, estados, transições, ramificações, processamento paralelo, checkpoints\u003c/td\u003e\n\u003ctd data-label=\"Mecanismos típicos de prevenção de falhas\"\u003eTransições proibidas, validação de estado, nós de aprovação, caminhos de recuperação\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eEm resumo, \u003cstrong\u003eo harness define o ambiente e os limites\u003c/strong\u003e, \u003cstrong\u003eo loop define as regras de repetição\u003c/strong\u003e e \u003cstrong\u003eo grafo define a estrutura dos caminhos possíveis\u003c/strong\u003e. Em sistemas reais, pode haver um loop dentro de um nó do grafo, enquanto o grafo inteiro é executado dentro de um único harness.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#como-os-m%C3%A9todos-de-controle-de-agentes-evolu%C3%ADram\" class=\"anchor\" id=\"como-os-métodos-de-controle-de-agentes-evoluíram\"\u003e\u003c/a\u003eComo os métodos de controle de agentes evoluíram\u003c/h2\u003e\n\u003ch3\u003e\n\u003ca href=\"#agentes-iniciais-workflows-predefinidos-complementavam-a-autonomia\" class=\"anchor\" id=\"agentes-iniciais-workflows-predefinidos-complementavam-a-autonomia\"\u003e\u003c/a\u003eAgentes iniciais: workflows predefinidos complementavam a autonomia\u003c/h3\u003e\n\u003cp\u003eOs primeiros agentes de IA generativa frequentemente esqueciam seus objetivos em tarefas longas, repetiam chamadas incorretas de ferramentas ou produziam resultados sem fundamento. Por isso, os desenvolvedores dividiam tarefas grandes em etapas menores e fixavam as entradas e saídas de cada etapa.\u003c/p\u003e\n\u003cp\u003eNessa abordagem, uma pessoa descreve todo o processo como uma cadeia, um fluxograma ou uma máquina de estados, enquanto o LLM assume tarefas limitadas, como classificação, extração, resumo e elaboração de rascunhos. Frameworks como LangGraph são usados para representar ramificações, ciclos, checkpoints e intervenção humana mantendo o estado.\u003c/p\u003e\n\u003cp\u003eNo entanto, a orquestração baseada em grafos não é uma abordagem ultrapassada que terminou em determinado ano. Ainda hoje, grafos explícitos são adequados para trabalhos em que auditabilidade, reprodutibilidade, conformidade regulatória ou procedimentos precisos de recuperação são importantes.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#melhoria-do-desempenho-dos-modelos-de-caminhos-fixos-ao-uso-din%C3%A2mico-de-ferramentas\" class=\"anchor\" id=\"melhoria-do-desempenho-dos-modelos-de-caminhos-fixos-ao-uso-dinâmico-de-ferramentas\"\u003e\u003c/a\u003eMelhoria do desempenho dos modelos: de caminhos fixos ao uso dinâmico de ferramentas\u003c/h3\u003e\n\u003cp\u003eCom o avanço da capacidade de raciocínio e de uso de ferramentas, um único agente passou a poder escolher ações como pesquisar, editar código, executar testes e ler arquivos de acordo com a situação. As abordagens da família ReAct são uma estrutura representativa que alterna raciocínio, ação e observação.\u003c/p\u003e\n\u003cp\u003eEssa mudança reduziu a necessidade de uma pessoa definir previamente todas as ramificações. Por outro lado, tornou mais importante gerenciar as informações lidas pelo agente, as permissões que ele possui, o custo de execução e os métodos de recuperação de erros. É nesse contexto que a engenharia de contexto e a engenharia de harness passam a ocupar o centro da prática.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#tarefas-longas-e-m%C3%BAltiplos-agentes-a-recombina%C3%A7%C3%A3o-de-loops-e-grafos\" class=\"anchor\" id=\"tarefas-longas-e-múltiplos-agentes-a-recombinação-de-loops-e-grafos\"\u003e\u003c/a\u003eTarefas longas e múltiplos agentes: a recombinação de loops e grafos\u003c/h3\u003e\n\u003cp\u003eEm tarefas longas, ciclos repetidos de planejamento, execução e verificação são mais importantes do que uma única chamada ao modelo. Quando vários agentes participam, também é necessário especificar papéis, formatos dos entregáveis, permissões e condições de encerramento. Ao mesmo tempo, deixar loops autônomos completamente sem supervisão pode causar explosão de custos, novas tentativas infinitas, hacking de recompensa e otimização de objetivos incorretos.\u003c/p\u003e\n\u003cp\u003ePor isso, os sistemas modernos de agentes são projetados para \u003cstrong\u003ecombinar trechos em que a autonomia é permitida com trechos controlados de forma determinística\u003c/strong\u003e, em vez de eliminar a autonomia. Isso não é um simples retorno às antigas cadeias fixas, mas uma forma de cercar a execução flexível com estados, transições e políticas.\u003c/p\u003e\n\u003cp\u003eEssa mudança representa mais uma alteração de ênfase no projeto do que uma cronologia exata. Grafos, loops e harnesses coexistem desde o início e continuam sendo usados em conjunto.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#o-que-a-engenharia-de-harness-abrange\" class=\"anchor\" id=\"o-que-a-engenharia-de-harness-abrange\"\u003e\u003c/a\u003eO que a engenharia de harness abrange\u003c/h2\u003e\n\u003cp\u003eO harness não é o modelo-base em si, mas \u003cstrong\u003eo sistema de execução que envolve o modelo para que ele realize o trabalho de fato\u003c/strong\u003e. Mesmo usando o mesmo modelo, a taxa de sucesso, o custo, a segurança e a reprodutibilidade podem variar muito conforme o harness.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#principais-componentes-de-um-harness\" class=\"anchor\" id=\"principais-componentes-de-um-harness\"\u003e\u003c/a\u003ePrincipais componentes de um harness\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003eSistema de instruções\u003c/strong\u003e: diretrizes do sistema, regras do repositório, padrões de código, prioridades e ações proibidas\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eFornecimento de contexto\u003c/strong\u003e: pesquisa, seleção de arquivos, resumo, memória e inserção de documentos no momento necessário\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eInterfaces de ferramentas\u003c/strong\u003e: edição de arquivos, terminal, navegador, banco de dados e APIs externas\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003ePermissões e isolamento\u003c/strong\u003e: escopo de leitura e gravação, acesso a informações secretas, restrições de rede e sandbox\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eMecanismos de verificação\u003c/strong\u003e: testes, linters, verificação de tipos, validação de schemas e checagem de fatos\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eAprovação humana\u003c/strong\u003e: aprovação de ações difíceis de reverter, como implantação, pagamento, exclusão e envio externo\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eObservabilidade\u003c/strong\u003e: registros de chamadas, custos, latência, erros, histórico de alterações e fundamentos das decisões\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003ePolíticas de recuperação\u003c/strong\u003e: novas tentativas, restauração do estado anterior, interrupção da tarefa e encaminhamento ao responsável\u003c/li\u003e\n\u003c/ol\u003e\n\u003cp\u003eArquivos de instruções de projeto ou hooks do Claude Code podem ser vistos como exemplos de componentes de um harness. No entanto, uma funcionalidade específica de um produto não representa todo o harness.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#diferen%C3%A7a-em-rela%C3%A7%C3%A3o-%C3%A0-engenharia-de-contexto\" class=\"anchor\" id=\"diferença-em-relação-à-engenharia-de-contexto\"\u003e\u003c/a\u003eDiferença em relação à engenharia de contexto\u003c/h3\u003e\n\u003cp\u003eA engenharia de contexto otimiza quais informações e instruções devem ser incluídas na chamada atual ao modelo. Isso inclui recuperar apenas documentos relevantes por meio de pesquisa, resumir conversas antigas, salvar o estado da tarefa em arquivos externos e separar o contexto por subtarefa.\u003c/p\u003e\n\u003cp\u003eA engenharia de harness é mais ampla. Além do contexto, ela abrange permissões de ferramentas, ambiente de execução, aprovações, verificações, logging e limites de custo. Portanto, a engenharia de contexto é uma parte central do harness, mas é impreciso usar os dois termos como se tivessem exatamente o mesmo significado.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#o-essencial-na-engenharia-de-loops-s%C3%A3o-as-condi%C3%A7%C3%B5es-de-encerramento\" class=\"anchor\" id=\"o-essencial-na-engenharia-de-loops-são-as-condições-de-encerramento\"\u003e\u003c/a\u003eO essencial na engenharia de loops são as condições de encerramento\u003c/h2\u003e\n\u003cp\u003eUm loop faz com que o agente verifique o resultado depois de produzi-lo e tente novamente caso seja insuficiente. O importante não é a repetição em si, mas \u003cstrong\u003ea definição de progresso e as condições de interrupção\u003c/strong\u003e.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#tipos-representativos-de-loops\" class=\"anchor\" id=\"tipos-representativos-de-loops\"\u003e\u003c/a\u003eTipos representativos de loops\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\n\u003cstrong\u003eLoop de verificação\u003c/strong\u003e: após criar um rascunho, verifica-o com testes ou critérios de avaliação e corrige os itens que falharam.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eLoop orientado a eventos\u003c/strong\u003e: inicia uma tarefa quando ocorre um evento externo, como um e-mail, uma notificação, uma alteração de código ou dados de sensores.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eLoop de exploração\u003c/strong\u003e: investiga várias hipóteses ou fontes e ajusta o escopo da busca até obter evidências suficientes.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eLoop de melhoria\u003c/strong\u003e: escolhe a próxima estratégia com base no resultado anterior e nos valores de avaliação. Como otimizar apenas uma pontuação pode causar hacking de recompensa, são necessários vários critérios de avaliação e revisão humana.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eLoop de recuperação\u003c/strong\u003e: classifica a causa do erro, faz novas tentativas dentro do escopo permitido e encaminha a tarefa a uma pessoa caso o problema não seja resolvido.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e\n\u003ca href=\"#contratos-necess%C3%A1rios-para-loops-seguros\" class=\"anchor\" id=\"contratos-necessários-para-loops-seguros\"\u003e\u003c/a\u003eContratos necessários para loops seguros\u003c/h3\u003e\n\u003cp\u003eUm contrato entre agentes não é um contrato jurídico, mas uma especificação de execução que define entradas, saídas e responsabilidades. É recomendável incluir os seguintes itens.\u003c/p\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eItem do contrato\u003c/th\u003e\n\u003cth\u003eO que especificar\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eObjetivo\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eResultado que deve ser concluído e itens fora do escopo\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eEntrada\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eDados que podem ser usados, atualidade e nível de confiança\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eSaída\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eSchema JSON, formato do documento, evidências obrigatórias e resultados de testes\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003ePermissões\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eFerramentas permitidas, escopo de arquivos, envio externo e permissões de alteração\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eVerificação\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eTestes e critérios de avaliação que devem ser aprovados\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eOrçamento\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eTokens, tempo, número de chamadas e quantidade de tarefas paralelas\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eEncerramento\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eCondições de sucesso, ausência de progresso, esgotamento do orçamento e detecção de risco\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item do contrato\"\u003eEncaminhamento\u003c/td\u003e\n\u003ctd data-label=\"O que especificar\"\u003eQual pessoa ou agente assumirá em caso de falha\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eSe as condições de conclusão forem ambíguas, o agente poderá considerar que está avançando mesmo enquanto apenas altera frases ou repete a mesma pesquisa. Em vez de estabelecer somente um número máximo de repetições, é melhor considerar em conjunto a qualidade do resultado, o aumento de novas informações, a evolução dos erros e o custo.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#a-engenharia-de-grafos-estrutura-os-limites-da-autonomia\" class=\"anchor\" id=\"a-engenharia-de-grafos-estrutura-os-limites-da-autonomia\"\u003e\u003c/a\u003eA engenharia de grafos estrutura os limites da autonomia\u003c/h2\u003e\n\u003cp\u003eUm grafo representa o trabalho por meio de nós e conexões. Um nó pode ser uma chamada ao modelo, a execução de uma ferramenta, uma aprovação humana ou um processo de verificação, enquanto as conexões representam a próxima ação de acordo com o estado.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#diferen%C3%A7a-entre-cadeias-e-grafos\" class=\"anchor\" id=\"diferença-entre-cadeias-e-grafos\"\u003e\u003c/a\u003eDiferença entre cadeias e grafos\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\n\u003cstrong\u003eUma cadeia\u003c/strong\u003e é adequada para procedimentos lineares que seguem de A para B e de B para C.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eUm grafo\u003c/strong\u003e é adequado para tarefas que exigem ramificações condicionais, repetições, execução paralela, recuperação de falhas e salvamento intermediário.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eUm grafo dinâmico\u003c/strong\u003e permite que o modelo proponha a próxima subtarefa ou o próximo caminho durante a execução.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eUm grafo restrito\u003c/strong\u003e faz com que o modelo se mova somente entre os nós e as transições permitidos, mesmo quando é ele que faz a escolha.\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eO objetivo do projeto moderno de grafos não é fazer com que uma pessoa decida previamente todas as ações. Trata-se de inserir na estrutura \u003cstrong\u003econdições invariáveis que devem ser respeitadas\u003c/strong\u003e, como exigir a passagem por um nó de aprovação antes da exclusão de dados ou impedir a transição de um estado de falha nos testes para o estado de implantação.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#sinais-de-que-um-grafo-%C3%A9-necess%C3%A1rio\" class=\"anchor\" id=\"sinais-de-que-um-grafo-é-necessário\"\u003e\u003c/a\u003eSinais de que um grafo é necessário\u003c/h3\u003e\n\u003cp\u003eSe várias das condições abaixo se aplicarem, vale a pena considerar um grafo explícito.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eHá um ponto de recuperação claro ao qual se deve retornar após uma falha.\u003c/li\u003e\n\u003cli\u003eExiste uma etapa que exige obrigatoriamente aprovação humana.\u003c/li\u003e\n\u003cli\u003eÉ necessário executar várias tarefas em paralelo e depois combinar os resultados.\u003c/li\u003e\n\u003cli\u003eAs ferramentas ou permissões disponíveis variam de acordo com o estado.\u003c/li\u003e\n\u003cli\u003eÉ necessário auditar ou reproduzir todo o caminho de execução.\u003c/li\u003e\n\u003cli\u003eUm loop de um único agente repete a mesma falha.\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eTransformar em grafo até mesmo um simples resumo de documento ou uma única conversão de dados pode apenas aumentar a complexidade.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#ordem-de-aplica%C3%A7%C3%A3o-pr%C3%A1tica-come%C3%A7ar-pelo-harness-e-expandir-conforme-necess%C3%A1rio\" class=\"anchor\" id=\"ordem-de-aplicação-prática-começar-pelo-harness-e-expandir-conforme-necessário\"\u003e\u003c/a\u003eOrdem de aplicação prática: começar pelo harness e expandir conforme necessário\u003c/h2\u003e\n\u003cp\u003ePara a maioria das equipes, a ordem a seguir é realista.\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003eDefina uma única tarefa e os critérios de sucesso.\u003c/strong\u003e Primeiro, reúna as entradas, as saídas esperadas e os casos de falha.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eCrie um harness mínimo.\u003c/strong\u003e Forneça apenas o contexto e as ferramentas necessários e configure permissões, testes, logs e limites de custo.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eConstrua um conjunto de avaliação.\u003c/strong\u003e Inclua não apenas casos normais, mas também solicitações ambíguas, documentos incorretos, erros de ferramentas e tentativas de exceder permissões.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eTransforme em loops os pontos que exigem repetição.\u003c/strong\u003e Permita novas tentativas apenas nos trechos em que a verificação e a correção realmente elevam a qualidade.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003ePromova para um grafo quando as ramificações e a recuperação se tornarem complexas.\u003c/strong\u003e Especifique estados e transições e coloque nós de aprovação antes de ações arriscadas.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eUse múltiplos agentes apenas quando a separação do trabalho trouxer benefícios.\u003c/strong\u003e Se não forem necessárias exploração paralela ou diferentes funções especializadas, um único agente pode ser mais simples e barato.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch2\u003e\n\u003ca href=\"#diferen%C3%A7as-de-aplica%C3%A7%C3%A3o-em-programa%C3%A7%C3%A3o-e-pesquisa\" class=\"anchor\" id=\"diferenças-de-aplicação-em-programação-e-pesquisa\"\u003e\u003c/a\u003eDiferenças de aplicação em programação e pesquisa\u003c/h2\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003eItem\u003c/th\u003e\n\u003cth\u003eTarefas de programação\u003c/th\u003e\n\u003cth\u003eTarefas de pesquisa\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item\"\u003ePossibilidade de verificação\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de programação\"\u003eA verificação automática por testes, build e checagem de tipos é relativamente fácil\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de pesquisa\"\u003eÉ necessário avaliar de forma abrangente a qualidade das fontes, omissões e evidências conflitantes\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item\"\u003eValor da exploração dinâmica\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de programação\"\u003ePode ser limitado quando o escopo das alterações está claro\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de pesquisa\"\u003eÉ alto ao comparar diferentes caminhos de pesquisa e hipóteses\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item\"\u003ePrincipais riscos\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de programação\"\u003eAlterações incorretas, vulnerabilidades de segurança e código ajustado apenas aos testes\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de pesquisa\"\u003eAlegações sem fontes, materiais duplicados e viés de confirmação\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"Item\"\u003eControles adequados\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de programação\"\u003eLimitação do escopo do repositório, testes, revisão de diff e aprovação de implantação\u003c/td\u003e\n\u003ctd data-label=\"Tarefas de pesquisa\"\u003eRegistro de fontes, pesquisa independente, busca de evidências contrárias e verificação de citações\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003eNão se pode afirmar categoricamente que workflows dinâmicos sejam sempre ineficientes para programação e sempre vantajosos para pesquisa. Uma migração de grande escala que possa ser testada pode ser adequada a agentes autônomos, enquanto uma consulta factual com resposta clara pode ser mais eficiente com um procedimento fixo de pesquisa. As variáveis centrais não são a área, mas \u003cstrong\u003ea clareza do objetivo, a possibilidade de verificação automática, o espaço de exploração e o custo dos erros\u003c/strong\u003e.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#a-revis%C3%A3o-de-c%C3%B3digo-n%C3%A3o-desaparece-o-que-muda-%C3%A9-a-unidade-de-revis%C3%A3o\" class=\"anchor\" id=\"a-revisão-de-código-não-desaparece-o-que-muda-é-a-unidade-de-revisão\"\u003e\u003c/a\u003eA revisão de código não desaparece; o que muda é a unidade de revisão\u003c/h2\u003e\n\u003cp\u003eQuando agentes escrevem código, os desenvolvedores passam a assumir mais a função de supervisionar requisitos, design, resultados de testes, escopo das alterações e riscos, em vez de digitar diretamente cada linha. Resumos de Pull Requests e relatórios de agentes podem acelerar a revisão.\u003c/p\u003e\n\u003cp\u003eNo entanto, ler apenas o resumo e aprovar não é uma opção padrão segura. Alterações omitidas pelo agente ou lógicas que ele compreendeu de forma incorreta podem não aparecer nem mesmo no resumo. Nas situações abaixo, é necessário revisar diretamente o diff original e o código relacionado.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eAlterações em autenticação, pagamentos, dados pessoais, criptografia e controle de acesso\u003c/li\u003e\n\u003cli\u003eAlterações no schema do banco de dados ou migrações irreversíveis\u003c/li\u003e\n\u003cli\u003eCódigo sensível a desempenho e concorrência\u003c/li\u003e\n\u003cli\u003eRefatorações de grande escala fora do escopo dos testes\u003c/li\u003e\n\u003cli\u003eAlterações em dependências externas, configurações de implantação e tratamento de informações secretas\u003c/li\u003e\n\u003cli\u003eCasos em que a explicação do agente não corresponde ao diff real\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eHuman-in-the-loop não significa que uma pessoa apenas pressione formalmente um botão. Também inclui fornecer evidências das alterações, resultados de testes, possibilidades de falha e procedimentos de reversão para que a pessoa possa tomar uma decisão.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#armadilhas-frequentes\" class=\"anchor\" id=\"armadilhas-frequentes\"\u003e\u003c/a\u003eArmadilhas frequentes\u003c/h2\u003e\n\u003ch3\u003e\n\u003ca href=\"#m%C3%BAltiplos-agentes-sem-prop%C3%B3sito\" class=\"anchor\" id=\"múltiplos-agentes-sem-propósito\"\u003e\u003c/a\u003eMúltiplos agentes sem propósito\u003c/h3\u003e\n\u003cp\u003eAumentar o número de agentes gera custos de coordenação de papéis, chamadas duplicadas, transferência de contexto e combinação de resultados. Se não houver necessidade de exploração paralela a partir de diferentes perspectivas nem motivo para separar o contexto, um único agente é melhor.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#workflows-din%C3%A2micos-sem-limites\" class=\"anchor\" id=\"workflows-dinâmicos-sem-limites\"\u003e\u003c/a\u003eWorkflows dinâmicos sem limites\u003c/h3\u003e\n\u003cp\u003ePermitir que o agente continue criando subtarefas faz com que o custo de tokens e chamadas de ferramentas aumente rapidamente. O custo é determinado aproximadamente pela soma do custo dos tokens de entrada e saída em cada etapa, do custo das ferramentas, do número de agentes paralelos e da quantidade de repetições. É necessário limitar separadamente o número de chamadas, a quantidade de execuções simultâneas, o orçamento total e o tempo máximo de execução.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#otimiza%C3%A7%C3%A3o-de-uma-%C3%BAnica-m%C3%A9trica-de-avalia%C3%A7%C3%A3o\" class=\"anchor\" id=\"otimização-de-uma-única-métrica-de-avaliação\"\u003e\u003c/a\u003eOtimização de uma única métrica de avaliação\u003c/h3\u003e\n\u003cp\u003eSe o único objetivo for a taxa de aprovação nos testes, podem surgir otimizações incorretas, como enfraquecer os testes ou ocultar o tratamento de exceções. É necessário usar em conjunto qualidade, segurança, volume de alterações, custo, latência e avaliação humana.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#confundir-inser%C3%A7%C3%A3o-de-documentos-com-fine-tuning\" class=\"anchor\" id=\"confundir-inserção-de-documentos-com-fine-tuning\"\u003e\u003c/a\u003eConfundir inserção de documentos com fine-tuning\u003c/h3\u003e\n\u003cp\u003eOs resultados podem mudar de forma persistente por meio da pesquisa de documentos ou das instruções do projeto, mas os pesos do modelo não são alterados. Em sentido amplo, isso pode ser descrito como um efeito de aprendizagem do sistema, mas, rigorosamente, trata-se de adaptação por meio de memória externa e contexto. Os documentos ou o índice de pesquisa precisam ser preservados para que as mudanças sejam mantidas nas execuções seguintes.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#avalia%C3%A7%C3%A3o-seguran%C3%A7a-e-viabilidade-econ%C3%B4mica-frequentemente-negligenciadas-na-opera%C3%A7%C3%A3o\" class=\"anchor\" id=\"avaliação-segurança-e-viabilidade-econômica-frequentemente-negligenciadas-na-operação\"\u003e\u003c/a\u003eAvaliação, segurança e viabilidade econômica frequentemente negligenciadas na operação\u003c/h2\u003e\n\u003cp\u003eO projeto de agentes não termina no diagrama de arquitetura. Na operação real, é importante ter \u003cstrong\u003eum sistema que meça o que realmente aconteceu, e não apenas o que foi permitido\u003c/strong\u003e.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#m%C3%A9tricas-operacionais-m%C3%ADnimas\" class=\"anchor\" id=\"métricas-operacionais-mínimas\"\u003e\u003c/a\u003eMétricas operacionais mínimas\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003eTaxa de sucesso das tarefas e taxa de correções humanas\u003c/li\u003e\n\u003cli\u003eCusto de modelos e ferramentas por tarefa e tempo total de execução\u003c/li\u003e\n\u003cli\u003eNúmero de repetições e proporção de chamadas consumidas sem progresso\u003c/li\u003e\n\u003cli\u003eNúmero de solicitações de aprovação, recusas e tentativas de exceder permissões\u003c/li\u003e\n\u003cli\u003eChamadas incorretas de ferramentas e taxa de sucesso da recuperação\u003c/li\u003e\n\u003cli\u003eProporção de resultados enviados sem fontes ou testes\u003c/li\u003e\n\u003cli\u003eGrau de variação dos resultados para a mesma entrada\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch3\u003e\n\u003ca href=\"#condi%C3%A7%C3%B5es-invari%C3%A1veis-necess%C3%A1rias-para-a-seguran%C3%A7a\" class=\"anchor\" id=\"condições-invariáveis-necessárias-para-a-segurança\"\u003e\u003c/a\u003eCondições invariáveis necessárias para a segurança\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003eAs instruções de documentos externos não têm prioridade superior à política do sistema.\u003c/li\u003e\n\u003cli\u003eInformações secretas não são expostas desnecessariamente na entrada do modelo nem nos logs.\u003c/li\u003e\n\u003cli\u003eAs permissões de leitura são separadas das permissões de gravação, exclusão e implantação.\u003c/li\u003e\n\u003cli\u003eEnvios externos e ações irreversíveis exigem aprovação separada ou verificação por políticas.\u003c/li\u003e\n\u003cli\u003eO agente não pode modificar arbitrariamente seus próprios critérios de avaliação, testes ou logs de auditoria.\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eÉ mais seguro impor essas condições invariáveis por meio de sandbox, controle de acesso, transições de grafo e verificadores independentes do que por uma única frase no prompt. A gestão de riscos da IA generativa deve abranger não apenas a precisão do modelo, mas também o ambiente operacional, a supervisão humana e a resposta a incidentes.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#qual-conceito-deve-ser-aprendido-primeiro\" class=\"anchor\" id=\"qual-conceito-deve-ser-aprendido-primeiro\"\u003e\u003c/a\u003eQual conceito deve ser aprendido primeiro\u003c/h2\u003e\n\u003cp\u003eNa prática atual, o primeiro conceito a dominar é a engenharia de harness. Um contexto preciso, privilégio mínimo, verificação automática, logs, aprovações e limites de custo podem reduzir muitas falhas de um único agente.\u003c/p\u003e\n\u003cp\u003eEm seguida, adicione loops com condições de encerramento às tarefas em que a repetição melhora a qualidade. Quando as ramificações, o processamento paralelo, a recuperação e os procedimentos de aprovação se tornarem complexos, represente-os explicitamente com grafos. Antes de adotar termos complexos, a prioridade é tornar mensuráveis os objetivos, as permissões, as evidências, os custos e as condições de interrupção do agente.\u003c/p\u003e\n","tags":["Engenharia de contexto","Engenharia de harness","Agentes de IA","Claude Code","Desenvolvimento de IA","Agente de programação"],"faqs":[{"question":"Qual é a diferença entre engenharia de harness e engenharia de prompts?","answer":"A engenharia de prompts lida principalmente com as instruções e formulações fornecidas ao modelo. A engenharia de harness é o projeto de um ambiente de execução mais amplo, que inclui não apenas prompts, mas também busca de contexto, ferramentas, permissões, sandbox, testes, logs, aprovação humana e recuperação de erros."},{"question":"Engenharia de contexto e engenharia de harness significam a mesma coisa?","answer":"Não. A engenharia de contexto se concentra em selecionar, buscar, resumir e organizar as informações que o modelo precisa saber no momento. A engenharia de harness lida, além da gestão de contexto, com permissões, ferramentas, validação, limites de custos e políticas operacionais."},{"question":"Qual é a diferença mais importante entre um loop e um grafo?","answer":"Um loop define o que deve ser repetido, como planejamento, execução, validação e correção, e quando parar. Um grafo define quais estados existem e como é possível passar de um estado para outro. Um grafo pode conter um ou mais loops."},{"question":"Todos os agentes de AI precisam de um framework de grafos como o LangGraph?","answer":"Não. Para tarefas simples e curtas, um único agente e um harness mínimo podem ser suficientes. O valor de um grafo aumenta quando são necessários ramificações condicionais, processamento paralelo, salvamento intermediário, recuperação de falhas, aprovação humana ou auditoria dos caminhos de execução."},{"question":"Um sistema multiagente sempre apresenta desempenho melhor do que um único agente?","answer":"Não. Um sistema multiagente é útil quando são necessários pesquisa paralela, diferentes funções especializadas e separação de contexto. Se as funções se sobrepuserem ou os objetivos forem vagos, isso poderá apenas aumentar o trabalho duplicado, os erros de transferência, a demora e os custos."},{"question":"Como impedir que o loop de um agente se repita infinitamente?","answer":"É necessário definir não apenas um número máximo de repetições, mas também orçamentos de tempo, tokens, chamadas de ferramentas e custos. O sistema deve considerar como falta de progresso uma situação em que não haja novas informações nem redução de erros e ser projetado para interromper a execução ou encaminhá-la a uma pessoa quando determinado limite for atingido."},{"question":"É suficiente revisar apenas o resumo do Pull Request do código escrito pela AI?","answer":"O resumo é apenas um material de apoio e não substitui as alterações originais. Em alterações de alto risco, como autenticação, pagamentos, dados pessoais, migração de dados e configurações de implantação, é necessário revisar diretamente o diff real, a cobertura dos testes, as dependências e os procedimentos de reversão."},{"question":"Se os documentos da empresa forem fornecidos continuamente ao modelo, isso significa que ele foi treinado?","answer":"Os resultados podem mudar de forma persistente, mas isso não significa que os pesos do modelo tenham sido atualizados. Trata-se de uma adaptação no nível do sistema, que preserva documentos externos, índices de busca, memória e instruções para fornecê-los novamente em execuções posteriores, e deve ser diferenciada do ajuste fino em sentido estrito."},{"question":"A engenharia de grafos representa um retorno aos workflows fixos do início?","answer":"Não necessariamente. Os grafos modernos se aproximam mais de um controle híbrido: permitem que o agente planeje de forma autônoma e selecione ferramentas em determinados trechos, ao mesmo tempo que restringem explicitamente transições perigosas e pontos de aprovação obrigatória."},{"question":"O que deve ser definido primeiro ao projetar um harness?","answer":"Primeiro, é necessário definir os critérios de sucesso da tarefa e o custo das falhas. Em seguida, é recomendável fornecer apenas o contexto e as ferramentas necessários e estabelecer permissões mínimas, validação automática, logs de execução, limites de custos e condições de interrupção."}],"sources":[{"url":"https://www.anthropic.com/research/building-effective-agents","title":"Anthropic — Construindo agentes eficazes","type":"source"},{"url":"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents","title":"Anthropic — Engenharia de contexto eficaz para agentes de IA","type":"source"},{"url":"https://www.anthropic.com/engineering/multi-agent-research-system","title":"Anthropic — Como construímos nosso sistema de pesquisa multiagente","type":"source"},{"url":"https://docs.langchain.com/oss/python/langgraph/overview","title":"Visão geral do LangGraph","type":"source"},{"url":"https://arxiv.org/abs/2210.03629","title":"ReAct: Sinergia entre raciocínio e ação em modelos de linguagem","type":"source"},{"url":"https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf","title":"NIST AI 600-1 — Estrutura de Gestão de Riscos de Inteligência Artificial: Perfil de Inteligência Artificial Generativa","type":"source"}],"images":[{"id":662,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6ODI0NSwicHVyIjoiYmxvYl9pZCJ9fQ==--3a03e254c3d24990df4c3fc46145a5db24e457ba/ai-eb0e40fe.webp","is_representative":true,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"중앙 AI 시스템을 순환 화살표와 성공·실패 노드 그래프가 둘러싼 다이어그램","caption":"AI 에이전트의 실행 루프와 보안 검증, 분기 경로를 시각화한 구성도다.","description":null},"en":{"alt":"Central AI system surrounded by loop arrows and a graph of success and failure nodes","caption":"The diagram visualizes an AI agent’s execution loop, security checks, and branching paths.","description":null},"ja":{"alt":"中央のAIシステムを循環矢印と成功・失敗ノードのグラフが囲む図","caption":"AIエージェントの実行ループ、セキュリティ検証、分岐経路を可視化している。","description":null},"es":{"alt":"Sistema de IA central rodeado de flechas cíclicas y una red de nodos de éxito y error","caption":"El diagrama representa el bucle de ejecución, las verificaciones y las rutas de un agente de IA.","description":null},"id":{"alt":"Sistem AI pusat dikelilingi panah berulang dan graf simpul keberhasilan serta kegagalan","caption":"Diagram ini memvisualkan loop eksekusi, pemeriksaan keamanan, dan jalur bercabang agen AI.","description":null},"pt":{"alt":"Sistema central de IA cercado por setas cíclicas e uma rede de nós de sucesso e falha","caption":"O diagrama mostra o ciclo de execução, as verificações de segurança e as rotas de um agente de IA.","description":null},"zh-hant":{"alt":"中央 AI 系統周圍環繞循環箭頭與成功、失敗節點組成的路徑圖","caption":"此圖呈現 AI 代理的執行迴圈、安全檢查與分支路徑。","description":null},"de":{"alt":"Zentrales KI-System, umgeben von Kreispfeilen und einem Netz aus Erfolgs- und Fehlerknoten","caption":"Das Diagramm zeigt Ausführungsschleife, Sicherheitsprüfungen und verzweigte Pfade eines KI-Agenten.","description":null}}},{"id":663,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6ODI1MSwicHVyIjoiYmxvYl9pZCJ9fQ==--cea797c99aabaa4b8f760264327fe2ee8b34b423/ai-23d7d97a.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"보안 하네스 속 AI 로봇이 도구 루프와 분기 그래프를 거쳐 검증 및 경고 단계로 이동하는 흐름","caption":"AI 에이전트가 보호된 환경에서 반복 작업과 그래프 분기를 거쳐 사람의 검증을 받는 과정을 보여준다.","description":null},"en":{"alt":"AI robot moves from a secure harness through a tool loop and branching graph to validation and a warning gate","caption":"The diagram shows an AI agent progressing through protected execution, iterative tools, graph branches, and human validation.","description":null},"ja":{"alt":"保護されたAIロボットがツールのループと分岐グラフを経て検証と警告ゲートへ進む流れ","caption":"AIエージェントが保護環境から反復処理、グラフ分岐、人による検証へ進む工程を示している。","description":null},"es":{"alt":"Un robot de IA pasa de un entorno seguro a un bucle de herramientas, un grafo ramificado y una puerta de alerta","caption":"El diagrama muestra a un agente de IA avanzando por ejecución protegida, iteraciones, ramas y validación humana.","description":null},"id":{"alt":"Robot AI bergerak dari lingkungan aman melalui loop alat dan graf bercabang menuju validasi serta gerbang peringatan","caption":"Diagram ini menunjukkan agen AI melalui eksekusi terlindungi, proses berulang, cabang graf, dan validasi manusia.","description":null},"pt":{"alt":"Robô de IA passa de um ambiente seguro por um ciclo de ferramentas e grafo ramificado até validação e alerta","caption":"O diagrama mostra um agente de IA avançando por execução protegida, iterações, ramificações e validação humana.","description":null},"zh-hant":{"alt":"AI 機器人從安全框架經過工具迴圈與分支圖，走向人工驗證及警示閘門","caption":"此圖呈現 AI 代理從受保護執行、反覆工具操作和圖形分支走向人工驗證的流程。","description":null},"de":{"alt":"KI-Roboter durchläuft eine sichere Umgebung, eine Werkzeugschleife und einen verzweigten Graphen bis zur Warnschranke","caption":"Die Grafik zeigt einen KI-Agenten bei geschützter Ausführung, iterativen Abläufen, Graphverzweigungen und menschlicher Prüfung.","description":null}}}],"published_at":"2026-08-16T00:45:12+09:00","updated_at":"2026-08-16T00:45:12+09:00","license":"cc_by","translation_status":"reviewed","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/en/articles/ai-agent-harness-loop-graph-engineering"}