Budgets, deadlines e cancelamento são sinais diferentes

Não trate todos como maxSteps.

Um timeout é especialmente perigoso: ele diz que o caller não recebeu confirmação, não que o efeito não ocorreu. Antes de repetir, consulte por idempotency key ou reconcilie o estado externo.

Retry: classifique primeiro, durma depois

Retry sem hipótese apenas repete o acidente. A AWS documenta timeouts, retries, backoff com jitter e a necessidade de tornar retries seguros com APIs idempotentes; a Stripe documenta idempotency keys para evitar a duplicação de operações em tentativas repetidas (AWS, AWS sobre APIs idempotentes, Stripe).

Backoff controla pressão; idempotência controla duplicação; reconciliação resolve resultado desconhecido. São três mecanismos diferentes.

Leases e ownership: um run, um escritor autorizado

Quando workers podem retomar ou disputar a mesma tarefa, uma chave idempotente por tool não basta. Você também precisa saber quem tem autoridade para avançar o estado.

Uma lease deve carregar runId, ownerId, versão/fencing token, acquiredAt, expiresAt e regra de renovação. Cada escrita compara o fencing token atual. Worker com lease expirada pode terminar uma computação, mas não pode publicar o resultado.

Kubernetes usa objetos Lease para coordenação, heartbeats e leader election (documentação oficial). O padrão é útil como referência, mas a implementação do seu agente ainda precisa definir relógio, consistência, renovação, expiração e fencing.

Ownership também precisa existir no plano organizacional:

“O agente decidiu” não é uma linha aceitável de ownership.

Checkpointing: retome o run, não a confusão

Checkpoint seguro acontece depois de uma transição confirmada, não no meio de um side effect desconhecido. Persista:

• versão do objetivo, policy, prompt e tool registry;
• fase e última transição confirmada;
• evidências e artifacts por referência;
• budget consumido e restante;
• attempts e idempotency keys;
• lease/fencing token;
• aprovações pendentes;
• deadline e cancel state;
• hash do checkpoint anterior.

Ao retomar, valide compatibilidade. Uma aprovação concedida para tool:v2 não autoriza silenciosamente tool:v3. A documentação atual do OpenAI Agents SDK descreve RunState serializável para pause/resume e recomenda versionar tarefas pendentes quando definições de agent, tools ou SDK podem mudar (fonte primária).

Human-in-the-loop é uma transição, não uma mensagem no chat

Pare antes da ação sensível. O pedido de aprovação deve conter:

• ação exata e argumentos relevantes;
• motivo e critério que a tornou necessária;
• side effects e blast radius;
• reversibilidade e plano de rollback;
• evidência coletada;
• prazo da aprovação;
• opções approve, reject e modify;
• versão do contrato aprovado.

O OpenAI Agents SDK documenta um fluxo em que tools marcadas para aprovação interrompem o run, o estado é serializado, uma pessoa aprova ou rejeita a chamada específica e o run retoma (documentação). O princípio é mais importante que o SDK: aprovação precisa ser vinculada à intenção, aos argumentos e à versão, não a um “sim” genérico.

Reversibilidade: prefira preparar antes de efetivar

Ordene ações por risco:

1. ler;
2. simular;
3. gerar diff ou plano;
4. escrever em staging/draft;
5. pedir aprovação;
6. efetivar;
7. verificar;
8. compensar se necessário.

Nem todo efeito tem rollback verdadeiro. Um email enviado não pode ser “desenviado”; um segredo exposto não volta a ser secreto. Nesses casos, reduza blast radius antes da ação e trate compensação como mitigação, não viagem no tempo.

Quatro falhas que parecem inteligência, mas são controle ruim

Falha 1 — Parada por narrativa

Sintoma: o agente afirma “concluído”, mas não há eval ou mudança verificável.
Causa: texto final foi aceito como condição de parada.
Diagnóstico: trace termina em output do modelo; não existe verifying → succeeded.
Correção: só o controlador promove succeeded, com assertions sobre evidência.
Artefato preventivo: eval que falha quando sucesso não tem evidenceRef.

Falha 2 — Retry que duplica efeito

Sintoma: dois tickets, cobranças, posts ou patches após timeout.
Causa: retry de escrita sem chave de intenção e sem reconciliação.
Diagnóstico: duas chamadas equivalentes, request IDs diferentes, resultado inicial desconhecido.
Correção: idempotency key estável, lookup por intenção e retry apenas para classe permitida.
Artefato preventivo: teste de contrato que envia a mesma intenção duas vezes e exige um único efeito.

Falha 3 — Dois workers acreditam ser o dono

Sintoma: estado oscila, artifacts se sobrescrevem ou duas ações incompatíveis passam.
Causa: retomada concorrente sem lease/fencing.
Diagnóstico: spans sobrepostos para o mesmo runId, ambos com escrita aceita.
Correção: lease com expiração e fencing token validado em toda mutação.
Artefato preventivo: teste de split-brain em que o worker atrasado perde permissão de commit.

Falha 4 — Run zumbi depois de cancelar

Sintoma: usuário cancela, mas uma tool termina e o agente publica mesmo assim.
Causa: cancelamento não propagado; checkpoint retomado sem revalidar intenção e deadline.
Diagnóstico: cancelledAt anterior ao side effect, sem guardrail na saída.
Correção: cancellation token descendente, verificação antes do commit e estado terminal monotônico.
Artefato preventivo: teste que cancela entre execução e commit e exige zero publicação.

As quatro falhas têm a mesma raiz: o modelo recebeu autoridade que pertencia ao controlador.

Artefato copiável: contrato de execução do loop

Este YAML não depende de framework. Salve como agent-loop-contract.yaml e adapte owners, limites e tools:

apiVersion: agents.example/v1
kind: AgentLoopContract
metadata:
  name: discount-policy-fix
  owner: checkout-platform
spec:
  goal:
    version: 3
    statement: Fix the VIP discount rule without regressions.
    successCriteria:
      - spec_read_before_write
      - targeted_patch_only
      - deterministic_eval_passed
      - release_evidence_emitted
  stateMachine:
    initial: ready
    terminal: [succeeded, failed, cancelled]
    pausable: [waiting_human]
  budgets:
    maxSteps: 12
    maxToolCalls: 8
    maxTokens: 50000
    maxCostUsd: 2.00
    deadlineSeconds: 300
  cancellation:
    propagateToTools: true
    retryAfterCancel: false
    verifyBeforeCommit: true
  concurrency:
    leaseSeconds: 30
    renewEverySeconds: 10
    fencingRequired: true
  checkpoint:
    afterEveryTransition: true
    include: [phase, evidence, budgets, attempts, idempotencyKeys, approvals]
    requireCompatiblePolicyVersion: true
  retry:
    maxAttemptsPerAction: 3
    backoff: exponential_with_full_jitter
    retryOn: [rate_limited, transient_5xx]
    neverRetryOn: [validation_error, permission_denied, policy_block, cancelled]
  tools:
    allow: [read_spec, apply_patch, run_eval]
    sideEffectsRequireIdempotency: true
    productionWritesRequireApproval: true
  safety:
    sandboxByDefault: true
    redactSecretsFromTrace: true
    preferReversibleActions: true
  observability:
    traceFields: [runId, state, action, tool, attempt, latencyMs, costUsd, evidenceRef]
    releaseEvidenceRequired: true
  evals:
    trajectory: [spec_before_patch, no_action_after_cancel, stop_after_success]
    outcome: [discount_policy_passes, regression_suite_passes]

O arquivo só vira governança se runtime e CI rejeitarem violações. Configuração que ninguém aplica é documentação aspiracional.

Evals: avalie resultado, trajetória e controle

Um eval de output pergunta “a resposta está correta?”. Um eval de agente também pergunta “como chegamos aqui?”. A Anthropic descreve tasks, trials, graders e a necessidade de avaliar sistemas multi-turn que usam tools e modificam ambientes (fonte primária).

Construa a suíte em quatro camadas:

Rode múltiplos trials quando a política usa modelo, mas mantenha assertions determinísticas para invariantes. Métricas úteis incluem task success, ações proibidas, retries por classe, tempo até parada, custo por sucesso, handoffs corretos e taxa de reconciliação de resultados desconhecidos.

Não otimize apenas pass rate. Um agente que passa mais vezes porque ignora aprovação está pior.

Tracing: reconstrua decisões sem registrar segredos

Um trace útil permite responder:

• qual objetivo e versão estavam ativos;
• qual estado entrou na decisão;
• qual ação foi proposta, autorizada e executada;
• qual tool/version recebeu quais argumentos redigidos;
• qual observação voltou;
• qual budget foi consumido;
• qual retry, guardrail, aprovação ou cancelamento ocorreu;
• por que o run parou.

OpenTelemetry define traces como caminhos de execução compostos por spans com timestamps, atributos, eventos, links e status (documentação). O guia do OpenAI Agents SDK expõe configuração de tracing e controle sobre a inclusão de dados sensíveis (documentação). Use ambos como referência, mas defina uma taxonomia própria para run, decision, tool, eval, approval e checkpoint.

Observabilidade não significa guardar prompt e output brutos para sempre. Redija segredos, tokenize identificadores quando possível, separe acesso operacional de acesso analítico e defina retenção.

Safety: reduza autoridade e blast radius

Guardrails do modelo ajudam em decisões semânticas; não substituem controles determinísticos.

• allowlist de tools por tipo de tarefa;
• credenciais de menor privilégio e curta duração;
• sandbox para código e arquivos não confiáveis;
• separação entre read, draft e commit;
• limites por tenant, ambiente e recurso;
• aprovação vinculada a argumentos;
• validação de schema antes e depois da tool;
• detecção e redaction de segredos;
• bloqueio de paths e destinos fora do escopo;
• kill switch fora do processo do agente.

O SDK de Agents da OpenAI documenta guardrails de input, output e tool, incluindo tripwires que interrompem a execução (documentação). A regra arquitetural é simples: guardrail precisa alterar o fluxo, não apenas acrescentar um aviso ao prompt.

Custo: meça por resultado aceito

Tokens são só uma parte. O custo de um run inclui inferência, tools pagas, compute de sandbox, armazenamento, tracing, revisão humana, retries e incidentes.

Acompanhe pelo menos:

• custo por tentativa e por sucesso aceito;
• p50/p95 de tempo até estado terminal;
• tool calls úteis versus descartadas;
• retries e reconciliações por classe;
• minutos de revisão humana;
• taxa de runs abandonados, cancelados e expirados;
• custo de coordenação em sistemas multiagente.

Compare com o baseline mais simples. Um agente só vence quando melhora resultado líquido sob as mesmas restrições de risco, não quando gera mais atividade.

Toy vs. produção

O loop mínimo ensina a separação. A versão de produção precisa demonstrar, em testes e operação, que essa separação sobrevive a processo morto, rede ambígua, concorrência, custo, erro humano e mudança de versão.

Checklist de prontidão

Antes do primeiro run

• Objetivo versionado e critérios observáveis definidos.
• Baseline sem agente medido.
• Estados e transições válidas documentados.
• Tools têm owner, schema, permissões, timeout, retry e side effects.
• Ações de escrita têm idempotência ou reconciliação explícita.
• Budgets, deadline e custo são bloqueados fora do modelo.
• Cancelamento chega às tools e é verificado antes do commit.
• Lease/fencing existe quando mais de um worker pode escrever.
• Checkpoint é versionado e compatível com pause/resume.
• Aprovação de alto risco está ligada aos argumentos exatos.
• Evals cobrem outcome, trajetória, controle e falhas injetadas.
• Traces permitem reconstrução sem expor segredos.
• Runbook nomeia owner, alerta, rollback e kill switch.

Antes de declarar sucesso

• Cada critério aponta para evidência verificável.
• O estado externo foi reconciliado após resultados desconhecidos.
• Nenhuma ação ocorreu após cancelamento ou lease expirada.
• Gate determinístico passou.
• Custo e budgets ficaram dentro dos limites.
• Riscos não testados foram declarados.
• Evidência de release registra versões, ações, evals e decisão final.

Exercícios

1. Faça run_eval falhar uma vez com rate_limited. Implemente retry com full jitter, teto de três tentativas e consumo de budget.
2. Persista um checkpoint após cada transição. Mate o processo após apply_patch e retome sem aplicar o patch duas vezes.
3. Execute dois workers para o mesmo runId. Implemente lease com fencing e prove que o worker atrasado não consegue publicar.
4. Cancele o run entre o retorno da tool e o commit. O teste deve provar que o estado externo não muda.
5. Transforme apply_patch em ação de produção que exige aprovação vinculada ao hash do diff. Altere o diff e prove que a aprovação antiga perde validade.

Você aprendeu quando consegue explicar e testar não apenas o que o agente fez, mas quem autorizou, com qual estado, sob quais limites, com qual evidência e por que ele parou.

Critérios de sucesso

Considere o loop pronto para um piloto limitado somente quando:

1. todos os estados terminais são alcançáveis por testes e nenhum deles executa nova tool;
2. todo side effect repetido com a mesma intenção produz no máximo um efeito observável;
3. timeout, rate limit, input inválido, permissão negada e cancelamento seguem políticas diferentes;
4. um checkpoint pode ser retomado após crash sem perder budget, approvals ou idempotency keys;
5. split-brain é bloqueado por lease/fencing;
6. cancelamento vence retry, fallback e conclusão tardia;
7. sucesso exige eval independente e evidência referenciável;
8. traces reconstroem a trajetória sem armazenar segredos proibidos;
9. custo por sucesso e baseline determinístico são comparáveis;
10. owners conseguem executar kill switch, handoff, rollback ou compensação em exercício controlado.

Esses critérios não provam segurança absoluta. Eles provam algo mais útil: que o loop tem contratos falsificáveis e falha de maneira observável.

Síntese

O menor agente é um ciclo: observar, orientar, decidir, agir, verificar e parar. O agente de produção é esse mesmo ciclo cercado por estado durável, tools estreitas, memória com proveniência, budgets, deadlines, cancelamento, leases, checkpoints, retries idempotentes, aprovação, evals, tracing, safety e owners.

Comece pelo while. Depois retire do modelo tudo que não deveria depender de linguagem: autoridade, limites, transições, contabilidade e definição de sucesso.

Autonomia útil não é liberdade para continuar. É capacidade de avançar dentro de um contrato — e parar com evidência.

Fontes primárias

• Anthropic, Building Effective Agents — distinção entre workflows e agents, padrões de composição, feedback ambiental e condições de parada.
• Anthropic, Demystifying Evals for AI Agents — tasks, trials, graders e avaliação de trajetórias multi-turn.
• OpenAI Agents SDK, Running agents — lifecycle do runner, limites de turnos, tracing, erros e integrações de execução durável.
• OpenAI Agents SDK, Human-in-the-loop — interrupções, aprovação/rejeição, serialização, retomada e versionamento de estado pendente.
• OpenAI Agents SDK, Guardrails — guardrails de input, output e tools e tripwires de interrupção.
• Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models — raciocínio, ação e observação ambiental em trajetórias intercaladas.
• Kubernetes, Leases — coordenação, heartbeats e leader election com objetos Lease.
• AWS Builders’ Library, Timeouts, retries, and backoff with jitter — controle de retries em sistemas distribuídos.
• AWS Builders’ Library, Making retries safe with idempotent APIs — intenção do caller, idempotência e side effects sob retry.
• Stripe, Idempotent requests — contrato de idempotency keys em requests repetidos.
• OpenTelemetry, Traces — traces, spans, eventos, atributos, links e status.

Escopo e validade

• As capacidades específicas de SDKs refletem documentação verificada em 12 de agosto de 2026; revalide versões e defaults antes de implementar.
• O código é didático e local: não prova confiabilidade de modelo, SDK ou infraestrutura externa.
• Os valores de budget do YAML são exemplos, não recomendações universais.
• Leases, idempotência e compensações exigem garantias do armazenamento e do domínio; nomes iguais não produzem semântica correta automaticamente.