Condições de Parada

Intenção

Definir, fora do modelo, quando um agente terminou, quando desistiu e quando precisa de ajuda. Serve para todo agente que roda em loop e precisa acabar sempre num estado conhecido.

Problema

Larissa colocou em produção um agente de pesquisa. Ele recebe uma pergunta de mercado, busca na web, lê fontes e escreve um relatório. Nas primeiras semanas deu certo. Depois começaram três tipos de reclamação.

Algumas tarefas nunca terminavam: o agente seguia buscando “mais uma fonte” até o orçamento acabar. Outras terminavam cedo demais: depois de duas buscas, o agente escrevia um relatório confiante com informação rasa. E algumas terminavam com “não consegui concluir”, sem dizer o que tinha encontrado e por que tinha parado.

Os três problemas têm a mesma raiz. “Terminar” estava definido em uma frase do prompt: “quando tiver informação suficiente, escreva o relatório”. O modelo decidia sozinho o que era suficiente, e não havia nenhum outro jeito de acabar.

A pergunta que este padrão responde: como garantir que todo loop de agente termine, e termine no estado certo?

Solução

Trate o fim como parte do design, com quatro saídas explícitas, cada uma checada por código sempre que possível:

• Sucesso: o objetivo foi cumprido, e há um critério verificável para isso (o teste passa, o relatório tem N fontes válidas).
• Limite: o orçamento de passos, tempo ou custo acabou. O agente entrega o que tem e diz que parou no limite.
• Desistência: o agente concluiu que não consegue, por falta de acesso ou de informação. Ele explica o motivo.
• Pedido de ajuda: o agente precisa de uma decisão ou de um dado que só uma pessoa tem.

O modelo pode sinalizar sucesso, desistência ou pedido de ajuda com uma ferramenta própria ou com saída estruturada. O código confirma o sucesso quando dá, e o limite é sempre do código.

Não é uma ideia exótica. No texto “Building effective agents” (dezembro de 2024), a Anthropic recomenda que agentes tenham condições de parada, como um número máximo de iterações, para manter o controle. Este padrão leva a recomendação adiante: além do teto, cada jeito de terminar ganha um nome e um tratamento.

Exemplo trabalhado

Volte ao agente de Larissa. O critério de sucesso virou regra em código: o relatório precisa citar pelo menos três fontes independentes, e todo link precisa abrir. O orçamento é de 25 passos. Um trace com as quatro saídas funcionando:

step 6   finish(kind="done", note="Relatório pronto")
         verify: 2 fontes válidas de 3 exigidas         -> rejeitado
         tool_result: "Critério não cumprido: falta 1 fonte independente."
step 7   web_search("market share pagamentos instantâneos 2026")
...
step 14  finish(kind="done", note="Relatório pronto, 4 fontes")
         verify: 4 fontes válidas, todos os links abrem -> aceito
stop.reason = success

O primeiro “concluí” do modelo era o mesmo relatório raso das reclamações. A verificação devolveu o motivo, e o modelo continuou. Sem ela, a tarefa teria parado no passo 6 com uma fonte a menos.

Agora uma pergunta sem resposta pública, como a margem de lucro de uma empresa de capital fechado. Duas saídas são boas: no passo 9 o agente chama finish(kind="give_up", note="Nenhuma fonte pública traz a margem; achei só estimativas de terceiros, listadas abaixo"). Ou, se continuar tentando, o código para no passo 25 e entrega o resumo do que achou, com stop.reason = limit. A saída ruim, que o padrão impede, é um relatório confiante com um número inventado.

Estrutura

flowchart TD
  L(["1. Volta do loop"]):::llm --> B{"2. Orçamento ok?"}
  B -->|não| LIM(["3. Parada por limite"]):::io
  B -->|sim| S{"4. Sinal do modelo"}
  S -->|continuar| L
  S -->|concluí| V["5. Verificar critério"]:::tool
  V -->|passou| OK(["6. Sucesso"]):::io
  V -->|falhou| L
  S -->|não consigo| G(["7. Desistência explicada"]):::io
  S -->|preciso de ajuda| H((("8. Humano"))):::human

1. Cada volta do loop termina com uma decisão do modelo.
2. O código checa o orçamento antes de qualquer outra coisa.
3. Sem orçamento, a execução para com o estado atual e o motivo.
4. O modelo sinaliza uma de quatro intenções, de forma estruturada.
5. “Concluí” não basta: o código checa o critério de sucesso quando ele é verificável.
6. Sucesso confirmado encerra a tarefa.
7. Desistência é uma saída válida, com explicação do que foi tentado.
8. Pedido de ajuda pausa a execução até uma pessoa responder.

Pseudocódigo

schema Signal { kind: "continue" | "done" | "give_up" | "need_help", note: string }

function run(task):
    while true:
        if not budget.check(steps=25, seconds=600, dollars=2.00):      # 2
            return finish("limit", summarize(state))                    # 3

        reply = llm_with_tools(SYSTEM, TOOLS + [signal_tool], state)    # 1 e 4
        signal = reply.signal or Signal("continue")
        trace.span("signal", signal)

        if signal.kind == "done":
            if verify(task.success_criteria, state):                    # 5
                return finish("success", reply.text)                    # 6
            state.add("O critério ainda não foi cumprido: " + failed_checks())
        elif signal.kind == "give_up":
            return finish("gave_up", signal.note)                       # 7
        elif signal.kind == "need_help":
            answer = human.ask(signal.note)                              # 8
            state.add(answer)
        else:
            state.add(execute(reply.tool_calls))

Cenários reais

• Agente de código. Sucesso tem critério verificável: os testes passam e o lint não reclama. O agente não pode declarar “pronto” com teste vermelho.
• Agente de navegador para tarefas repetitivas. O portal pode estar fora do ar ou pedir um captcha. Desistência e pedido de ajuda evitam horas de cliques inúteis.
• Pesquisa profunda com citações. “Suficiente” vira regra: pelo menos N fontes independentes por afirmação, ou o relatório sai marcado como incompleto.

Aplicabilidade

• Qualquer agente que roda em loop sem uma pessoa olhando cada passo.
• Tarefas com critério de sucesso verificável por código: testes, schema, contagem, consulta.
• Tarefas em que pode faltar acesso, dado ou permissão, e desistir cedo é melhor que tentar para sempre.
• Fluxos em que uma decisão de negócio pode aparecer no meio.

Quando não usar

• Uma chamada única ao modelo, sem loop. Use max_tokens e trate o motivo de parada da API.
• Uma chain fixa, em que o código já define cada passo e o fim. Ali o fim é o último passo.
• Um chat em que o usuário controla cada turno. O usuário é a condição de parada.

Como implementar

1. Escreva o critério de sucesso de cada tipo de tarefa em uma frase verificável.
2. Transforme o que der em código: comando de teste, validação de schema, contagem de fontes.
3. Dê ao modelo uma ferramenta finish (ou saída estruturada) com os quatro tipos de sinal.
4. Implemente o orçamento como em Adicionar Orçamento ao Loop.
5. Escreva o fechamento de cada saída: o que o usuário recebe em caso de limite, desistência ou espera.
6. Registre o tipo de parada no trace de toda execução.
7. Monte casos de eval para cada saída, inclusive tarefas impossíveis de propósito.

Como escolher os limites

Não chute o teto. Olhe os traces das execuções que terminaram com sucesso e veja quantos passos, segundos e reais elas usaram. O teto fica acima da grande maioria delas, com folga, para que o limite pegue execuções presas e não tarefas difíceis.

Suponha que 95% das execuções bem-sucedidas usem até 14 passos e a mais longa use 19. Um teto de 25 deixa espaço para o caso difícil e corta o loop preso cedo. Um teto de 200 “para garantir” deixa uma execução presa gastar dez vezes mais antes de parar.

Revise os limites quando o tipo de tarefa mudar. Um teto certo para “corrigir um teste” é curto demais para “migrar um módulo”.

O fechamento de cada saída

Cada saída precisa de uma resposta pensada para quem recebe. Escreva as quatro antes de ir para produção:

Pense no agente de navegador que baixa boletos. “Não consegui” não ajuda ninguém. “O portal pediu um captcha na tela de login às 3h12; baixei 14 de 20 boletos, os 6 restantes estão listados abaixo” deixa a pessoa terminar o trabalho em dois minutos.

Erros comuns

• Limite que lança exceção. A tarefa some sem estado, sem registro e sem resposta. O limite é uma saída como as outras: entrega o que foi feito e diz que parou ali.
• Sucesso igual a “o modelo disse que acabou”. Se existe um teste, um schema ou uma contagem, use. A opinião do modelo só decide quando não há nada para checar.
• Prompt que empurra para a desistência. Frases como “na dúvida, desista” fazem a taxa de gave_up disparar. Diga quando desistir: falta de acesso, dado inexistente, permissão negada.
• Pedido de ajuda sem ninguém do outro lado. Se a pessoa demora horas, a execução fica pendurada. Defina um prazo de espera e o que acontece quando ele vence.

Variações

• Critério por checagem externa. Em vez de o modelo dizer “concluí”, o código checa o estado a cada volta (o arquivo existe, o teste passou) e encerra sozinho.
• Detecção de estagnação. Sem progresso mensurável em N voltas (mesmos arquivos, mesma ferramenta, mesmo resultado), o código encerra com desistência.
• Parada por avaliador. Um segundo modelo julga se o resultado cumpre o critério. Útil quando o critério é qualitativo; é o laço do Avaliador e Otimizador.

Custo, latência e falhas

Como avaliar

• Distribuição de paradas: fração de sucesso, limite, desistência e ajuda por tipo de tarefa.
• Sucesso verdadeiro: das tarefas marcadas como sucesso, quantas passam na checagem independente do eval.
• Desistência correta: em tarefas impossíveis de propósito, o agente desiste em vez de inventar.

{ "task": "Baixe a fatura de setembro no portal X", "fixture": "portal_offline", "expected_stop": "gave_up" }

Monte pelo menos um caso por saída. Uma tarefa fácil espera success. Uma tarefa impossível de propósito (portal fora do ar, arquivo que não existe) espera gave_up. Uma tarefa que depende de uma decisão de negócio espera need_help. E uma fixture que faz a ferramenta responder “ok” sem progresso espera limit. Se o agente responde a tarefa impossível com success, você achou o caso mais perigoso: sucesso falso.

Em produção

• Atributo stop.reason em todo trace, com painel por tipo de tarefa.
• Alerta quando a fração de paradas por limite sobe. Normalmente é uma ferramenta quebrada ou uma mudança no mundo lá fora.
• Fila de revisão para desistências, que viram casos de eval ou melhorias nas ferramentas.
• Tempo de espera por ajuda humana como métrica própria.

Prós e contras

Código

As abas usam uma ferramenta finish com os sinais e um critério verificado por código. Python e TypeScript leem o sinal dentro do while. LangGraph lê o mesmo sinal numa aresta: limite, sucesso, desistência ou humano são destinos do grafo, não frases no prompt.

import subprocess
import time

import anthropic

client = anthropic.Anthropic()

FINISH = {
    "name": "finish",
    "description": "Chame quando terminar, desistir ou precisar de ajuda. Nunca responda sem chamar esta ferramenta.",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "kind": {"type": "string", "enum": ["done", "give_up", "need_help"]},
            "note": {"type": "string", "description": "Resultado, motivo da desistência ou pergunta para a pessoa"},
        },
        "required": ["kind", "note"],
        "additionalProperties": False,
    },
}


def tests_pass() -> bool:  # 5. critério verificável
    return subprocess.run(["pytest", "-q"], capture_output=True).returncode == 0


def run(task: str, tools: list, execute, ask_human, max_steps=25, max_seconds=600) -> dict:
    messages, start = [{"role": "user", "content": task}], time.monotonic()
    for _ in range(max_steps):
        if time.monotonic() - start > max_seconds:
            break
        reply = client.messages.create(
            model="claude-opus-5-5", max_tokens=8000, tools=tools + [FINISH], messages=messages,
        )
        messages.append({"role": "assistant", "content": reply.content})
        results = []
        for block in (b for b in reply.content if b.type == "tool_use"):
            if block.name != "finish":
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": execute(block)})
                continue
            kind, note = block.input["kind"], block.input["note"]
            if kind == "done" and tests_pass():
                return {"stop": "success", "result": note}               # 6
            if kind == "give_up":
                return {"stop": "gave_up", "result": note}               # 7
            content = ask_human(note) if kind == "need_help" else "Os testes ainda falham. Continue."
            results.append({"type": "tool_result", "tool_use_id": block.id, "content": content})
        messages.append({"role": "user", "content": results or "Use uma ferramenta ou chame finish."})
    return {"stop": "limit", "result": "Parei no limite. Último estado no trace."}  # 3

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const FINISH: Anthropic.Tool = {
  name: "finish",
  description: "Chame quando terminar, desistir ou precisar de ajuda. Nunca responda sem chamar esta ferramenta.",
  strict: true,
  input_schema: {
    type: "object",
    properties: {
      kind: { type: "string", enum: ["done", "give_up", "need_help"] },
      note: { type: "string" },
    },
    required: ["kind", "note"],
    additionalProperties: false,
  },
};

type Stop = { stop: "success" | "gave_up" | "limit"; result: string };

export async function run(
  task: string,
  tools: Anthropic.Tool[],
  execute: (b: Anthropic.ToolUseBlock) => Promise<string>,
  verify: () => Promise<boolean>,
  askHuman: (q: string) => Promise<string>,
  maxSteps = 25,
): Promise<Stop> {
  const messages: Anthropic.MessageParam[] = [{ role: "user", content: task }];
  for (let step = 0; step < maxSteps; step++) {
    const reply = await client.messages.create({
      model: "claude-opus-5-5", max_tokens: 8000, tools: [...tools, FINISH], messages,
    });
    messages.push({ role: "assistant", content: reply.content });
    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const b of reply.content) {
      if (b.type !== "tool_use") continue;
      if (b.name !== "finish") {
        results.push({ type: "tool_result", tool_use_id: b.id, content: await execute(b) });
        continue;
      }
      const { kind, note } = b.input as { kind: string; note: string };
      if (kind === "done" && (await verify())) return { stop: "success", result: note };
      if (kind === "give_up") return { stop: "gave_up", result: note };
      const content = kind === "need_help" ? await askHuman(note) : "O critério ainda falha. Continue.";
      results.push({ type: "tool_result", tool_use_id: b.id, content });
    }
    messages.push({ role: "user", content: results.length ? results : "Use uma ferramenta ou chame finish." });
  }
  return { stop: "limit", result: "Parei no limite. Último estado no trace." };
}

from typing import Literal

from langgraph.graph import END, START, StateGraph
from typing_extensions import TypedDict

class State(TypedDict):
    steps: int
    max_steps: int
    signal: str  # continue | done | blocked | help
    verified: bool
    output: str

def turn(state: State) -> dict:
    # 1. uma volta; o modelo devolve o sinal estruturado
    signal = ask_model(state)  # sua chamada, saída em schema
    return {"signal": signal, "steps": state["steps"] + 1}

def route(state: State) -> Literal["turn", "limit", "success", "give_up", "human"]:
    if state["steps"] >= state["max_steps"]:
        return "limit"  # 2 e 3
    if state["signal"] == "continue":
        return "turn"
    if state["signal"] == "done":
        return "success" if state["verified"] else "turn"  # 5
    if state["signal"] == "blocked":
        return "give_up"  # 7
    return "human"  # 8

graph = StateGraph(State)
graph.add_node("turn", turn)
graph.add_node("limit", lambda s: {"output": "parei no teto"})
graph.add_node("success", lambda s: {"output": "ok"})
graph.add_node("give_up", lambda s: {"output": "não consegui"})
graph.add_node("human", lambda s: {"output": "aguardando pessoa"})
graph.add_edge(START, "turn")
graph.add_conditional_edges("turn", route, ["turn", "limit", "success", "give_up", "human"])
for name in ("limit", "success", "give_up", "human"):
    graph.add_edge(name, END)
app = graph.compile()

Suporte por framework

Teste seu entendimento