Agentes de IA: como o loop funciona e quando deve parar

O modelo propõe a próxima ação. O software decide se ela pode ser executada, registra o que aconteceu e determina se uma nova chamada ao modelo está autorizada. Essa divisão de responsabilidades é o ponto de partida tanto para criar um primeiro agente quanto para investigar um que não parou de executar.

O comportamento dos frameworks descrito abaixo foi conferido na documentação oficial de cada fornecedor em 24 de outubro de 2026. A comparação coloca em termos equivalentes o que cada framework conta e em que momento seus controles entram em ação. Os exemplos com chamados de suporte e as políticas sugeridas são ilustrativos; não são resultados medidos em produção.

Como funciona o loop dos agentes de IA?

O ciclo útil é chamada ao modelo → chamada de ferramenta → observação → repetição, com uma saída sempre que continuar for desnecessário ou não for permitido.

Imagine um coordenador que distribui serviços a um técnico. O coordenador escolhe o próximo trabalho, o técnico o executa e o relatório do serviço orienta a decisão seguinte. Pedir uma inspeção não é o mesmo que realizá-la; uma mensagem tranquilizadora não comprova que o reparo deu certo.

No software, o coordenador é um grande modelo de linguagem, ou LLM. O técnico é uma ferramenta: uma função que consulta um banco de dados, busca documentos, executa um comando ou altera um registro. O ambiente de execução, ou runtime, é o código que conecta os dois.

Em uma tarefa hipotética de redigir uma resposta a um chamado, o registro de execução poderia ser assim: a primeira chamada ao modelo solicita o chamado; a segunda pede a política relevante; a terceira devolve um rascunho fundamentado nos dois. São 3 chamadas ao modelo e 2 execuções de ferramentas, dentro de uma única requisição à aplicação. Se o envio da resposta exige aprovação, a redação pode estar concluída enquanto o envio continua pendente.

Mantenha o estado da tarefa separado do histórico da conversa. O estado deve indicar qual chamado está sendo tratado, qual política foi aceita, se existe um rascunho e se o envio está autorizado. O histórico explica como se chegou até ali. Pedir repetidamente ao modelo que deduza tudo isso de uma conversa cada vez maior dificulta a supervisão do trabalho.

O que muda quando o agente trabalha em loop?

Um agente em loop pode escolher a próxima ação com base no resultado mais recente. Um fluxo fixo já conhece a sequência: buscar o chamado, buscar a política e produzir o rascunho. Use o loop adaptativo quando a próxima ação útil depender do que a anterior revelou. Use a sequência fixa quando essa incerteza não existir.

Onde entra o loop de um agente ReAct?

O loop de um agente ReAct conecta raciocínio e ação: o modelo usa as observações para orientar as ações seguintes. O projeto original ReAct descreve a alternância entre raciocínio e ações em um ambiente. Para monitorar a aplicação, registre as ações solicitadas, as observações e os resultados finais. Um relato do progresso não substitui uma confirmação de execução.

As três condições de parada que todo loop em produção precisa ter

Projete três saídas deliberadas: conclusão, esgotamento de limites e necessidade de intervenção humana. Essas são categorias de engenharia; não significa que todo SDK ofereça os mesmos três controles. Falhas abruptas, cancelamentos e erros irrecuperáveis também precisam de tratamento explícito.

Pare quando a tarefa estiver concluída

Defina o que significa concluir antes da primeira chamada ao modelo. Para um assistente de redação, pode ser um rascunho válido com referências às fontes relevantes. Para um assistente que executa ações, também pode ser necessária uma confirmação de gravação.

Separe “o modelo parou de solicitar ferramentas” de “o trabalho pedido foi concluído com sucesso”. O primeiro é um sinal do ambiente de execução. O segundo exige evidências específicas da tarefa. Um modelo pode parar porque não consegue prosseguir; nesse caso, a aplicação deve registrar o trabalho como bloqueado ou incompleto, sem apresentá-lo como bem-sucedido.

Não reinicie o loop automaticamente toda vez que uma resposta falhar na validação. Cada tentativa de correção precisa consumir os limites da mesma tarefa; caso contrário, o validador pode se tornar outra fonte de tentativas sem fim.

Pare quando um limite for atingido

Use limites independentes para etapas, consumo de recursos e tempo decorrido. Um teto de etapas restringe a repetição. Um orçamento de tokens ou de gastos limita o consumo. Um prazo impede que um modelo ou uma ferramenta lenta mantenha a tarefa aberta indefinidamente. Nenhum desses limites substitui os outros.

Confira os limites antes de admitir novas operações e atualize o consumo depois que elas terminarem. Um contador de chamadas concluídas não impede que uma requisição em andamento continue consumindo recursos. Se a aplicação promete um teto rígido, reserve capacidade para a próxima operação e considere o trabalho simultâneo antes de iniciá-la.

Aplique os limites à tarefa de negócio inteira, não apenas a uma invocação do SDK. Uma nova tentativa, uma retomada após aprovação ou um agente filho não deve ganhar uma cota nova de forma silenciosa. Se houver justificativa para continuar, amplie a cota por meio de uma decisão explícita da aplicação.

Human in the loop: pause o agente antes da ação

Um agente de IA com supervisão humana, ou human in the loop, deve pausar antes da operação que exige aprovação. Mostre a ação proposta, seu alvo e os argumentos relevantes. Salve a chamada pendente e o estado atual da tarefa; depois, aguarde uma decisão explícita.

No assistente de suporte, a aprovação deve valer para aquela resposta específica, enviada àquele destinatário específico. Aprovar um rascunho não deve conceder permissão irrestrita para mensagens futuras. Se o modelo mudar o destinatário ou o conteúdo depois da aprovação, reavalie a ação.

Registre a pausa como awaiting_approval, e não como completed. Uma rejeição deve levar a uma alternativa definida ou à interrupção do trabalho. Ela não deve provocar tentativas repetidas de executar a mesma operação por outra ferramenta. O guia de human in the loop aborda filas de aprovação e encaminhamento para instâncias de decisão.

Um loop de agente mínimo em pseudocódigo

O loop fica enxuto quando cada operação é cercada por verificações de política. Este é um pseudocódigo, não um código executável de SDK. O teto de 8 chamadas ao modelo é uma escolha ilustrativa da aplicação; defina seus limites a partir da tarefa e dos registros de execução observados.

state = new_job(task, max_model_calls=8, budget, deadline)

while true:
    if limit_reached(state):
        return stop("limit", partial_result=state)

    reserve_capacity_or_stop(state, next_model_call)
    response = call_model_with_deadline(state)
    record_model_call_usage_and_response(state, response)

    if response.is_final and not response.tool_calls:
        return validate_and_finish_or_stop_incomplete(response, state)

    if not response.tool_calls:
        return stop("no_action", partial_result=state)

    for index, call in enumerate(response.tool_calls):
        decision = validate_and_authorize(call, state)
        if decision == "denied":
            return stop("denied", partial_result=state)
        if decision == "needs_human":
            return pause_and_save(state, response.tool_calls[index:])

        reserve_capacity_or_stop(state, call)
        observation = execute_with_timeout_and_retry_cap(call)
        record_tool_usage(state, observation)
        append_matching_tool_result(state, call, bounded(observation))

    if no_progress(state):
        return stop("stalled", partial_result=state)

Os nomes das funções auxiliares carregam obrigações importantes. As reservas precisam considerar o trabalho que já está em andamento. Novas tentativas de executar ferramentas devem ter limites. Se uma gravação atingir o tempo limite e seu resultado for desconhecido, é preciso parar ou verificar o que de fato aconteceu antes de tentar de novo. Um erro fatal do modelo ou da ferramenta encerra a execução com uma falha registrada, em vez de deixar o fluxo seguir para outra iteração.

Ao salvar uma pausa, inclua as chamadas de ferramentas restantes, os resultados já obtidos e a cota consumida. Na retomada, continue o trabalho salvo e confira novamente a autorização e os limites. Reiniciar toda a tarefa pode repetir efeitos anteriores.

Observe a posição das verificações: a aprovação vem antes da execução da ferramenta, a contabilização do consumo vem depois do trabalho concluído, e a próxima iteração não pode começar apenas porque o modelo pediu.

Como cada framework controla o loop

OpenAI Agents SDK, Claude Agent SDK, Vercel AI SDK e LangGraph organizam o loop de formas diferentes. Compare as unidades de contagem e os pontos de parada antes de comparar os nomes das opções.

Esses nomes vêm das respectivas documentações: loop de OpenAI, loop de Claude, loop de Vercel e Graph API de LangGraph. Os links sobre o funcionamento das aprovações estão nas seções abaixo.

OpenAI Agents SDK: o Runner decide a continuidade

OpenAI Agents SDK é um framework cujo Runner chama o modelo, executa as ferramentas solicitadas, acrescenta os resultados e continua. Um handoff troca o agente ativo e dá continuidade à execução. O encerramento normal documentado ocorre quando há uma saída do tipo esperado e nenhuma chamada de ferramenta; ultrapassar max_turns gera MaxTurnsExceeded, a menos que isso seja tratado. Documentação de execução de agentes de OpenAI.

Para um assistente de suporte, isso oferece um ponto direto para limitar os turnos do modelo. A ressalva é a diferença entre encerrar uma execução e concluir uma ação de negócio: configure o contrato de saída e confira as evidências que a tarefa exige.

Para aprovações, ferramentas em Python podem declarar needs_approval; as chamadas pendentes aparecem em interruptions. Salve o RunState, aplique a aprovação ou a rejeição e retome. Uma execução pausada não é uma nova solicitação do usuário. Documentação de human in the loop de OpenAI.

Loop de Claude: limite tanto os turnos quanto os gastos

Claude Agent SDK incorpora o loop usado pelo Claude Code, incluindo ferramentas de arquivos e comandos. A opção maxTurns conta turnos de uso de ferramentas; maxBudgetUsd define um limite de gasto estimado. Quando não são configuradas, ambas ficam sem limite. Em Python, os nomes são max_turns e max_budget_usd. Documentação do agent loop de Claude.

Confira o subtipo do resultado: success, error_max_turns e error_max_budget_usd representam desfechos diferentes. No modo de execução única, um resultado de erro é seguido de uma exceção, então trate tanto o resultado quanto o fluxo de falha. Tratamento de resultados de Claude.

As permissões exigem o mesmo cuidado. allowedTools aprova automaticamente as ferramentas listadas; deixar uma ferramenta fora da lista não a remove. No modo de permissão padrão, chamadas que precisam de aprovação e não correspondem a nenhuma regra de autorização chegam a canUseTool. Confira a política completa de permissões antes de usar esse SDK para gravações sem supervisão. Permissões de Claude.

Para contabilizar o consumo de agentes filhos, Claude distingue usage, referente ao loop principal, de modelUsage, ou model_usage em Python, referente à árvore inteira. Use o total adequado ao investigar o consumo de uma tarefa. Documentação de custos e consumo de Claude.

Para acompanhar a implementação passo a passo, comece pelo guia de Claude Agent SDK do site.

Vercel AI SDK: stopWhen controla a próxima etapa

Vercel AI SDK permite controlar a continuidade por meio de stopWhen. A documentação atual usa isStepCount para limitar etapas e permite combinar várias condições, interrompendo quando qualquer uma for atendida. O padrão de ToolLoopAgent é 20 etapas, enquanto generateText e streamText têm como padrão uma geração. O ponto de entrada faz diferença. Controle do loop de Vercel, documentação de chamadas de ferramentas.

Uma etapa inclui uma geração e suas execuções locais de ferramentas. O ponto decisivo é que stopWhen é avaliado quando a última etapa contém resultados de ferramentas. Ele não pode desfazer o trabalho das ferramentas que produziu esses resultados. Portanto, controla a continuidade; não funciona como aprovação antes da ação. Chamadas de várias etapas em Vercel.

Use o mecanismo documentado de toolApproval para obter aprovação explícita do usuário. A documentação atual marca a propriedade antiga needsApproval, das ferramentas, como obsoleta. Aprovação de ferramentas em Vercel.

Para gerenciar o contexto, prepareStep roda antes de cada etapa e pode alterar mensagens ou configurações. Use esse ponto para fornecer o estado relevante, em vez de carregar todos os resultados brutos a cada vez. prepareStep de Vercel.

LangGraph e o loop de agentes em LangChain

LangGraph é um ambiente de execução de grafos: você conecta nós, que realizam trabalho, por meio de arestas, que determinam o que será executado em seguida. Em um loop de agente de LangChain construído sobre um grafo, deixe explícitos tanto o caminho de volta ao modelo quanto o caminho até END. Em Python, recursion_limit limita as superetapas do grafo; nós paralelos compartilham uma mesma superetapa. Não é um contador de chamadas de ferramentas. Graph API de LangGraph.

Defina recursion_limit no nível superior da configuração de invocação, fora de configurable. Atingir esse limite gera GraphRecursionError; em condições normais, um caminho de conclusão planejado deve encerrar a execução antes dessa saída de emergência. Limite de recursão de LangGraph.

Para revisão humana, interrupt() pausa o grafo. Use um mecanismo de checkpoint e um thread_id estável; depois, retome com Command(resume=...). A ressalva central: a retomada reinicia o nó interrompido desde o começo. O código anterior à interrupção pode rodar novamente. Coloque os efeitos depois da aprovação ou torne-os idempotentes, ou seja, faça com que repetir a execução não produza efeitos adicionais. Interrupções de LangGraph.

Escolha essa estrutura explícita de grafo quando as ramificações e a retomada do estado forem centrais para a tarefa. Para um primeiro assistente somente de leitura, com um ciclo simples de ferramentas, comece pelo menor ambiente de execução que atenda aos seus requisitos.

Por que uma execução chega a 40 etapas?

Antes de aumentar o teto, investigue o que mudou de uma etapa para outra. Uma execução longa pode representar trabalho útil, falhas repetidas ou um reinício que perdeu o registro do que já havia sido feito. O número, sozinho, não distingue essas situações.

Loops infinitos: repetição sem novas evidências

Um agente de suporte pode buscar uma política, receber um resultado vazio e repetir a mesma busca. A observação seguinte não acrescenta nada, então a próxima decisão pode reproduzir a mesma ação.

Registre o nome e os argumentos da ferramenta em formato normalizado, uma assinatura do resultado e um indicador de progresso da tarefa. A repetição sem mudança de estado deve acionar uma verificação de estagnação. Consultas periódicas legítimas também podem se repetir; por isso, defina uma política própria e limitada para elas, em vez de tratar toda duplicação como erro.

Mude alguma coisa antes de tentar de novo: um termo de busca, um identificador ausente, uma fonte de dados disponível ou o escopo da tarefa. Se nenhuma mudança útil for possível, informe o requisito que continua pendente ou peça ajuda. “Tentar de novo”, por si só, não é uma estratégia de recuperação.

Erros de ferramentas: diferencie falha recuperável de resultado desconhecido

Um argumento malformado, uma permissão negada e uma falha temporária de serviço exigem respostas diferentes. Devolva um erro conciso que permita ao modelo agir. Limite as novas tentativas em falhas recuperáveis e pare imediatamente diante de erros que não possam ser corrigidos com as permissões da tarefa.

Um tempo limite durante uma gravação é mais complicado: a operação pode ter sido concluída mesmo sem a resposta ter chegado. Antes de reenviar uma mensagem ao cliente ou criar outro registro, consulte o status da operação ou use uma chave de idempotência, um identificador estável que permite ao serviço reconhecer a mesma operação pretendida.

Preserve o trabalho bem-sucedido durante a recuperação. Se a leitura do chamado funcionou, mas a busca da política falhou, repetir a tarefa inteira acrescenta trabalho e pode reproduzir efeitos que já ocorreram.

Crescimento do contexto: leve adiante as decisões, não todos os dados brutos

Cada observação disputa a atenção da próxima chamada ao modelo com as instruções da tarefa e as evidências anteriores. Uma resposta extensa de ferramenta pode ser tecnicamente válida e, ainda assim, tirar o foco da decisão seguinte.

Limite as saídas das ferramentas, armazene artefatos grandes fora do prompt e devolva um resultado compacto com uma referência que permita recuperá-los. Mantenha as restrições aceitas, as aprovações e as ações confirmadas no estado persistente da aplicação. Um resumo pode descrever esses registros; não deve ser a única cópia deles.

O SDK de Claude documenta a compactação automática perto do limite de contexto e alerta que instruções iniciais podem se perder no resumo. Isso reforça a necessidade de preservar deliberadamente o estado crítico. Compactação de Claude. O artigo sobre context rot explica por que caber na janela de contexto não garante que as informações úteis sejam recuperadas.

Faça o registro de execução responder à pergunta de quem opera

Para cada tarefa, registre o identificador, a contagem de chamadas ao modelo, as tentativas de uso de ferramentas, o consumo, o tempo decorrido, as aprovações pendentes e o motivo da parada. Para cada operação, registre o que foi solicitado, o que foi concluído e se houve mudança no estado da tarefa.

Mantenha contadores separados para requisições ao modelo, execuções de ferramentas e etapas do ambiente de execução. Um painel que informa “40 etapas” sem definir a unidade não explica a execução. Inclua o trabalho dos agentes filhos e as novas tentativas na contabilização da tarefa principal. O guia de orquestração de agentes de IA explica a atribuição de responsabilidades quando o trabalho passa de um agente para outro.

Onde está o exagero em torno dos loops de agentes?

Mais iterações não comprovam mais progresso. Um loop oferece oportunidades repetidas de usar o retorno das ações; a qualidade desse retorno e a definição de sucesso determinam se a repetição ajuda.

Um modelo que diz “pronto” encerrou sua parte da troca. Um teto de etapas comprova que a execução teve um limite. Nenhum dos dois comprova que uma resposta de suporte está correta ou que a alteração solicitada aconteceu.

Usar um framework também não elimina a necessidade de definir permissões, persistência e recuperação. O framework fornece os mecanismos de execução. A aplicação define o que conta como sucesso e a autoridade para agir.

O loop de teste do agente é uma tarefa separada

Um loop de teste de agente avalia o comportamento com base em casos e critérios de aceitação. Ele pode envolver o loop de execução com um verificador que aceita o resultado ou devolve feedback para outra tentativa. A explicação de LangChain sobre engenharia de loops distingue execução, verificação e trabalho disparado por eventos.

O verificador também precisa de limites. Perguntar repetidamente a outro modelo se uma resposta é boa pode consumir a cota sem produzir evidências conclusivas. Sempre que possível, prefira verificações concretas: os campos obrigatórios existem, os registros citados correspondem aos originais, há uma confirmação de gravação ou um teste esperado passa.

Próximos passos para quem desenvolve e opera agentes

Para quem está criando o primeiro agente: comece com uma tarefa restrita, somente de leitura, um contrato explícito de conclusão e operações limitadas. Acrescente gravações quando conseguir apresentar a ação proposta, impor a autorização e se recuperar de um resultado ambíguo. Se a sequência já for conhecida, um fluxo fixo pode ser suficiente.

Para quem está investigando uma execução cara: examine chamadas repetidas, cadeias de novas tentativas e observações cada vez maiores antes de trocar o modelo ou ampliar os limites. Identifique qual etapa acrescentou evidências úteis e qual contador de fato interrompeu a tarefa.

Para equipes com um fluxo fixo confiável: mantenha-o até que a escolha adaptativa de ferramentas resolva um problema concreto. Um loop agrega valor quando os resultados intermediários determinam a próxima ação; a repetição, por si só, não justifica reconstruir o fluxo.

Para colocar em prática na segunda-feira: escolha uma tarefa representativa e exercite o caminho de conclusão, a saída por limite, a pausa para aprovação, a ação negada e o fluxo de falha de ferramenta. Confirme que cada um deixa um status claro e que a retomada preserva tanto o trabalho concluído quanto a cota restante.

Perguntas frequentes sobre o loop de agentes

Para receber guias práticos de criação e operação de sistemas de IA, assine a newsletter.