Glossário
66 termos de “Fundamentos do Harness de Agente: Laços e Controle”. Passe o cursor sobre a primeira ocorrência na lição para ver a definição.
| Termo | Definição | Fonte |
|---|---|---|
| harness | O nome coletivo do código de controle envolto ao redor do modelo — rodando ferramentas, dirigindo o loop, decidindo quando parar e quando esperar uma pessoa. O modelo só propõe ações; o harness decide se elas executam e se o loop continua. | How tool use works — Claude API |
| agente | Um LLM usando ferramentas com base em feedback do ambiente, em um loop. O modelo dirige dinamicamente seu próprio processo e decide quais ferramentas usar dentro do loop, em vez de seguir caminhos de código predefinidos. | Building Effective AI Agents — Anthropic Engineering |
| workflow | Um sistema em que LLMs e ferramentas são orquestrados por caminhos de código predefinidos — o que fazer primeiro e qual galho tomar já foram todos resolvidos de antemão por uma pessoa. | Building Effective AI Agents — Anthropic Engineering |
| loop | O processo repetido de o modelo propor → executar ferramentas → devolver o resultado ao modelo. Uma única ida e volta de chamada de ferramenta é só o caso especial em que o loop girou uma vez. | Building Effective AI Agents — Anthropic Engineering |
| decisões de controle de fluxo | Os julgamentos sobre “qual caminho tomar em seguida”. Em um workflow elas são fixadas no código; em um agente o modelo as toma dinamicamente dentro do loop — é essa a fronteira entre os dois. | The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) |
| controle de loop | O while loop que dirige modelo→ferramentas→modelo, lendo o stop_reason para decidir se gira mais uma rodada ou para. É o coração do harness. | The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) |
| despacho de ferramentas | Uma vez que o modelo propõe “chame esta ferramenta com estes parâmetros”, o código que roteia a requisição para a função de verdade, a executa e empacota a saída de volta em um tool_result. | The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) |
| gerenciamento de contexto | A peça do harness que gerencia o histórico produzido pelo loop — decidindo para onde ele vai, quanto dele permanece, como comprimir ou resumir, impedindo que o contexto inche até o orçamento de atenção se esgotar. | The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) |
| propor uma ação | O único trabalho do modelo a cada turno — olhar a conversa atual e emitir uma requisição estruturada de “o que quero fazer em seguida”, sem nunca executá-la. | How tool use works — Claude API |
| válvula de aprovação | Uma pausa inserida antes de executar uma ferramenta marcada como de alto impacto, mostrando a um humano “aqui está o que estou prestes a fazer” e executando só com um aval, retornando is_error numa recusa. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| ida e volta | Um ciclo completo de chamada de ferramenta: o modelo retorna tool_use, o host executa a ferramenta, empacota o tool_result, anexa à conversa e envia outra requisição. O loop é só a repetição de idas e voltas. | How tool use works — Claude API |
| feedback do ambiente | O resultado da execução da ferramenta devolvido ao modelo como entrada. O modelo decide seu próximo passo com base nesse feedback — é o combustível que empurra o loop adiante. | Building Effective AI Agents — Anthropic Engineering |
| autonomia | A propriedade que o agente tem de decidir dinamicamente seu próprio próximo passo e qual ferramenta usar. É por isso que agentes são úteis, e também significa custos mais altos e risco de erros que se acumulam. | Building Effective AI Agents — Anthropic Engineering |
| while loop | Uma estrutura while com o stop_reason como condição, que transforma uma única ida e volta em código: enquanto o stop_reason ainda for tool_use, gire mais uma rodada. | The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) |
| quatro passos | A sequência fixa que conecta idas e voltas em um loop: envie a requisição → leia o stop_reason e os blocos tool_use → rode as ferramentas e empacote os tool_result → anexe ao histórico e envie de novo. | How tool use works — Claude API |
| stop_reason | O campo na resposta do modelo que indica por que ele parou: tool_use significa que ele quer uma ferramenta e o loop continua, end_turn significa que ele está encerrando e o loop termina. | How tool use works — Claude API |
| tool_use | Um bloco de conteúdo que o modelo emite para requisitar uma chamada de ferramenta, carregando id / name / input. Ele significa que o modelo quer usar uma ferramenta, não que uma foi usada. | How tool use works — Claude API |
| tool_result | Um bloco de conteúdo que empacota a saída da execução da ferramenta de volta para o modelo, carregando tool_use_id para reivindicar a qual chamada ele responde, content para a saída, e is_error quando ela falhou. | Handle tool calls — Claude API |
| end_turn | Um valor de stop_reason que significa que o modelo não quer mais ferramentas e acha que terminou de falar. O loop termina naturalmente e devolve o texto final ao usuário. | How tool use works — Claude API |
| tool_use_id | O campo no tool_result que reivindica “esta é a resposta a qual chamada tool_use”, identificado casando com o id do bloco tool_use. Várias ferramentas em um só turno dependem disso para a correspondência um-para-um. | Handle tool calls — Claude API |
| is_error | Um campo opcional do tool_result, marcado como true quando a execução da ferramenta falhou, para o modelo saber que a chamada não teve sucesso e poder tentar de novo com argumentos diferentes ou tomar outra rota. | Handle tool calls — Claude API |
| callModel | A chamada em pseudocódigo nos loops esqueleto que representa “envie uma requisição ao modelo”. Implementações reais a trocam pelo client.messages.create do SDK. | How tool use works — Claude API |
| executeTool | A chamada nos loops esqueleto que representa “o host de fato vai e roda a ferramenta que o modelo nomeou”. A ação acontece neste passo, não quando o tool_use chegou. | How tool use works — Claude API |
| orçamento de atenção | O recurso finito do qual o modelo saca para processar contexto. Cada novo token o esgota em alguma medida; quanto mais longo o contexto, pior a capacidade do modelo de recuperar informação dele com precisão. | Effective context engineering for AI agents — Anthropic Engineering |
| condições de parada | Regras explícitas que o host impõe — como um número máximo de iterações — que param o loop independentemente do end_turn do próprio modelo, mantendo o controle do seu lado. | Building Effective AI Agents — Anthropic Engineering |
| máximo de turnos | A condição de parada rígida mais básica: um teto em quantas vezes o loop tem permissão para girar, parando na marca independentemente do que o modelo quer. | Building Effective AI Agents — Anthropic Engineering |
| parada rígida | Uma condição de parada que interrompe incondicionalmente na fronteira e encerra o loop de vez — nada continua automaticamente. Máximo de turnos e orçamento esgotado caem aqui. É um estado terminal. | Building Effective AI Agents — Anthropic Engineering |
| parada suave / suspensão | Uma pausa retomável em que o loop interrompe deliberadamente em um checkpoint, entrega o controle a uma pessoa, e consegue retomar daquele exato ponto uma vez que ela responda. Não é um fim. | Building Effective AI Agents — Anthropic Engineering |
| contador | Uma variável mantida fora do loop, que acumula entre rodadas, registrando quantas voltas o loop já deu. É o que permite à trava de máximo de turnos julgar. | Building Effective AI Agents — Anthropic Engineering |
| checkpoints | Pontos de pausa fincados nos elos da cadeia onde “se isto estiver errado, tudo depois disso é desperdício”, deixando o loop expor o estado intermediário para verificação ou aguardar feedback humano. | Building Effective AI Agents — Anthropic Engineering |
| needsHumanApproval | Um predicado nos exemplos de parada suave que julga “a próxima ação precisa do aval de uma pessoa antes?”. Quando ele bate, o loop suspende e entrega a cena aguardando a resposta humana. | Building Effective AI Agents — Anthropic Engineering |
| a tarefa terminou | A mais suave das quatro condições de parada — o modelo julga que acabou e devolve end_turn. A autoridade da decisão fica com o modelo, mas você ainda tem que confirmar que ela de fato terminou em vez de ter desistido pelo caminho. | Building Effective AI Agents — Anthropic Engineering |
| instantâneo da cena | O estado retomável entregue na pausa de parada suave — o messages atual mais a ação pendente em que empacou, empacotados juntos para uma pessoa poder retomar daquele exato ponto depois de lidar com ela. | Building Effective AI Agents — Anthropic Engineering |
| excesso de engenharia | Empilhar mecanismos quando a complexidade não melhora comprovadamente os resultados. Você só deveria adicionar complexidade quando ela comprovadamente melhora os resultados — mas condições de parada como o máximo de turnos são controle barato de grande retorno, não desta categoria. | Building Effective AI Agents — Anthropic Engineering |
| erros que se acumulam | Um passo errado seguido por todo turno subsequente continuando em cima do engano e amplificando o desvio. Nenhuma exceção é lançada, cada passo parece razoável, mas os erros crescem a juros compostos ao longo da cadeia. | Building Effective AI Agents — Anthropic Engineering |
| inchaço | Cada volta do loop enfia duas mensagens no histórico, só somando e nunca subtraindo, então cada requisição carrega um contexto progressivamente mais longo. As requisições ficam mais lentas e mais caras. | Effective context engineering for AI agents — Anthropic Engineering |
| apodrecimento do contexto | Conforme o contexto se alonga, a informação-chave se afoga no ruído e o modelo “consegue vê-la sem conseguir agarrá-la” — a recuperação degrada numa curva suave com o comprimento, não num penhasco abrupto. | Effective context engineering for AI agents — Anthropic Engineering |
| loop morto | Uma falha mecânica em que o código host está errado (como esquecer de reatribuir response no fim do corpo do loop), então o stop_reason fica congelado no valor antigo, a condição do while é permanentemente verdadeira, e o processo trava. | How tool use works — Claude API |
| giro em falso | O código está inteiramente correto, o loop legitimamente envia requisições e roda ferramentas a cada turno, e ainda assim nenhum progresso novo é feito — como chamar a mesma ferramenta de novo e de novo recebendo resultados quase idênticos e vazios. | Building Effective AI Agents — Anthropic Engineering |
| detecção de não-progresso | Uma comporta rígida feita para o giro em falso: o host observa “algo de novo está acontecendo?”, e se N turnos seguidos chamam a mesma ferramenta retornando saída quase idêntica, julga que não há progresso e sai do loop. | Building Effective AI Agents — Anthropic Engineering |
| teto de orçamento | Um teto de custo explícito definido para o loop, contado por turnos ou por tokens (dinheiro). Bateu no teto, para; leve quando contado por turnos, ou mais próximo do custo real quando contado por token. | Building Effective AI Agents — Anthropic Engineering |
| esgotamento de orçamento | A contagem de turnos vezes o contexto por turno se multiplicam para empurrar o custo para fora de controle. Um agente preso girando em falso pode queimar um gasto sério de API durante a noite sem realizar nada. | Building Effective AI Agents — Anthropic Engineering |
| governança de contexto | Gerenciar ativamente o histórico produzido pelo loop como fallback — comprimir turnos antigos, resumir resultados iniciais, descartar artefatos intermediários irrelevantes, pondo um freio no custo por turno. | Effective context engineering for AI agents — Anthropic Engineering |
| parada antecipada | Parar um loop que já derivou no momento em que algo parece fora do lugar, em vez de deixá-lo queimar o orçamento inteiro. Trabalha junto com os checkpoints para cortar o erro enquanto ele ainda é pequeno. | Building Effective AI Agents — Anthropic Engineering |
| retornos marginais decrescentes | A propriedade do contexto como recurso finito — cada pedaço adicional de histórico traz progressivamente menos valor. Então cada trecho de histórico deveria justificar “isto ainda vale a pena?”. | Effective context engineering for AI agents — Anthropic Engineering |
| agência excessiva | A vulnerabilidade que permite que ações danosas sejam realizadas em resposta a saídas inesperadas, ambíguas ou manipuladas de um LLM — independentemente do que causou o mau funcionamento. Quando o modelo está ligado a autoridade real, uma saída ruim pode disparar destruição. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| interromper | A mais direta das três intervenções humanas — seja lá o que o modelo queira fazer neste turno, o loop inteiro termina e nenhuma outra requisição sai. Depois de uma interrupção não há “e então”. | Building Effective AI Agents — Anthropic Engineering |
| redirecionar | Empurrar uma mensagem humana nova para dentro da conversa, mudando para o que o modelo se inclina em seguida, enquanto o loop segue rodando com a nova instrução. Redirecionar muda a direção, não se o loop vive. | Building Effective AI Agents — Anthropic Engineering |
| aprovar | Intervenção sobre uma ação específica de alto impacto — o loop chega nela, para, expõe “aqui está o que estou prestes a fazer”, e executa só se uma pessoa disser sim; pulando ou cancelando se disser não. Depois da aprovação o loop volta ao seu ritmo. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| humano no loop | Controle em que uma pessoa ganha a chance de dizer “espere aí” em uns poucos pontos críticos antes de ações irreversíveis aterrissarem, em vez de só ver os logs depois. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| comporta humana | Um checkpoint manual, além das comportas automáticas do próprio harness, que guarda os poucos cruzamentos de “se der errado, não dá para voltar”, onde a confiança da automação precisa do julgamento ao vivo de uma pessoa. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| irreversível | Ações que não podem ser desfeitas em um passo, ou só podem ser desfeitas a um custo enorme (apagar um banco de dados, mover dinheiro, publicar para fora, mudar a configuração de produção). As comportas de aprovação têm que vir antes delas. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| raio de impacto | Uma medida do alcance do impacto de uma operação e de sua irreversibilidade quando ela dá errado. Quanto maior o raio de impacto, mais cedo o ponto de confirmação tem que ficar. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| teste contrafactual | Uma autochecagem para julgar reversibilidade: se esta ação rodar e estiver errada, consigo desfazê-la em um passo, a baixo custo? Se não, a comporta tem que ficar cedo. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| askHuman | A chamada dentro da válvula de aprovação que pede a decisão de liberação a uma pessoa. Num terminal significa “imprima a ação pendente, leia uma linha de entrada”. Tem que terminar antes de executeTool. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| @anthropic-ai/sdk | O SDK oficial para Node. Use-o para trocar o pseudocódigo callModel do esqueleto pelo client.messages.create de verdade, dirigindo o mesmo loop de stop_reason. | How tool use works — Claude API |
| client.messages.create | O método do SDK que envia uma requisição ao modelo, recebendo model / max_tokens / tools / messages. É a substituição no mundo real para o callModel dentro do loop. | How tool use works — Claude API |
| runToolUses | Uma função que pega os blocos tool_use deste turno, de fato roda cada um, e empacota cada um num tool_result. A válvula de aprovação e o try/catch moram os dois dentro dela. | Handle tool calls — Claude API |
| runAgent | A função de entrada que carrega o loop inteiro do harness, ligando messages, as quatro válvulas de controle, o envio das requisições e a execução das ferramentas até o stop_reason deixar de ser tool_use. | How tool use works — Claude API |
| signatureOf | A função de assinatura da detecção de não-progresso — junta os nomes e parâmetros dos tool_use deste turno numa única string, usada para comparar com o turno anterior e detectar o giro em falso. | Building Effective AI Agents — Anthropic Engineering |
| response.usage | O campo nas respostas do modelo que reporta o consumo de tokens daquele turno (input_tokens + output_tokens). Base para tetos de orçamento contados em tokens. | Building Effective AI Agents — Anthropic Engineering |
| input_schema | O JSON schema na definição de uma ferramenta que descreve a estrutura da entrada. O modelo constrói o input do tool_use para casar com ele, fazendo os parâmetros se conformarem às exigências da ferramenta. | Handle tool calls — Claude API |
| try/catch | O invólucro de tolerância a erro em torno da execução da ferramenta — quando ela explode, não derrube o harness; empacote o erro num tool_result com is_error e devolva-o, dando ao modelo a chance de tentar de novo ou mudar de rota. | Handle tool calls — Claude API |
| válvulas de controle | O nome coletivo dos mecanismos de controle soldados ao loop, cada um guardando um ponto — máximo de turnos, teto de orçamento, detecção de não-progresso e aprovação para ações de alto impacto. As posições não são arbitrárias. | The 2026 Agent Engineering Roadmap — GitHub (codejunkie99/agent-roadmap-2026) |
| válvula de política | Uma generalização da válvula de aprovação — rotear ferramentas por nome em níveis allow (passagem direta), ask (confirmar antes da execução) e deny (sempre recusado), julgados antes de executeTool. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |
| alto impacto | Ações que produzem consequências externamente visíveis ou irreversíveis (write_file, http_post, delete_file). Só elas ganham a comporta de aprovação; leituras e consultas inofensivas passam direto. | LLM06:2025 Excessive Agency — OWASP Gen AI Security Project |