Orçamentos de chamadas externas que interrompem loops de agentes

Agentes autônomos não precisam de acesso ilimitado a serviços externos para serem úteis. Eles precisam de uma quantidade definida de permissão para tentar, esperar, repetir e gastar antes de devolver o trabalho. Sem esse limite, uma pequena ambiguidade, como um resultado de pesquisa vazio ou um trabalho atrasado, pode virar centenas de solicitações, efeitos colaterais duplicados e uma conta que ninguém esperava.

Um orçamento de chamadas externas é um contrato de execução para uma única execução do agente. Ele limita as tentativas de solicitação, o tempo transcorrido e a exposição financeira, e força uma parada visível quando qualquer limite se esgota. Trate-o como um limite operacional, não como uma sugestão no prompt do agente. Prompts são fáceis de reinterpretar quando o modelo tenta concluir uma tarefa; a aplicação do limite precisa ficar fora do modelo.

Um orçamento precisa contar tentativas, tempo e dinheiro separadamente

Um único limite não cobre todas as formas como um agente consome recursos. A quantidade de solicitações detecta loops. O limite de tempo transcorrido detecta consultas lentas e pausas entre novas tentativas. O limite de gastos detecta um pequeno número de ações caras. Cada medida identifica um modo diferente de falha e cada uma pode encerrar a execução enquanto as outras duas ainda têm saldo.

Conte tentativas, não respostas bem-sucedidas. Uma solicitação que sofreu tempo limite pode ter chegado ao provedor. Ela consumiu um socket, trabalho do provedor e muitas vezes uma entrada em uma API tarifada. Se você contar apenas os sucessos, o agente poderá fazer infinitas solicitações malsucedidas enquanto procura uma resposta de que goste.

Acompanhe pelo menos estes valores em cada execução:

• attempts_used e attempts_remaining, incluindo novas tentativas e redirecionamentos que geram uma nova solicitação externa
• deadline_at, usando um relógio monotônico para medir a duração, em vez do horário civil
• reserved_spend e settled_spend, na menor unidade prática de cobrança do provedor
• side_effect_attempts, uma contagem separada para ações que escrevem, enviam, criam ou compram
• budget_stop_reason, que registra o primeiro limite que impediu novos trabalhos

Não misture a quantidade de solicitações com os gastos atribuindo um preço inventado a cada chamada. Uma consulta de metadados e um endpoint de geração de modelo podem custar uma solicitação cada, embora suas faturas sejam muito diferentes. Por outro lado, uma API pode não informar preço para uma chamada que ainda cria um recurso de nuvem cobrável. Use um teto de solicitações mesmo quando houver uma estimativa de custo.

Um orçamento inicial útil para um agente que coleta dados de um conjunto conhecido de APIs pode permitir 40 tentativas no total, 10 minutos de execução e uma pequena reserva fixa. Um agente de implantação pode precisar de menos solicitações, mas de um limite mais rígido para efeitos colaterais. Um agente de pesquisa que segue URLs descobertas precisa de um escopo alcançável muito menor do que seu autor provavelmente proporia no início. Esses valores são hipóteses iniciais, não configurações universais. Meça as execuções normais e defina limites próximos o bastante para interromper comportamentos anormais antes que se transformem em um trabalho de limpeza.

O orçamento pertence a uma execução, não ao processo do modelo durante o dia. Quando o agente recebe uma nova tarefa, ele recebe um novo identificador de execução e uma nova alocação explícita. Um contador diário compartilhado esconde a execução cara entre o trabalho normal. Ele também permite que uma tarefa consuma a capacidade destinada a outra.

A reserva precisa ser feita antes da primeira chamada cara

Limites de gastos falham quando o sistema só descobre o preço depois de comprar algo. Reserve a cobrança máxima plausível antes da chamada, reduza imediatamente o orçamento restante e faça a conciliação mais tarde, quando o provedor retornar o uso real. Se a reserva não couber, negue a chamada antes que ela saia do seu perímetro.

Considere um agente que pode criar uma compilação hospedada. A solicitação do provedor aceita uma classe de máquina, região, tempo limite e tamanho do artefato, mas a cobrança exata só aparece depois da conclusão. O gateway do agente precisa de uma tabela de preços ou de uma estimativa conservadora. Ele não precisa de uma contabilidade perfeita para tomar uma decisão segura.

Um registro de reserva pode ter esta aparência:

{
  "run_id": "run_7c1f",
  "budget": {
    "attempts_remaining": 18,
    "deadline_at": "2025-04-21T14:42:00Z",
    "spend_remaining_cents": 1200
  },
  "reservation": {
    "action": "create_build",
    "maximum_cents": 850,
    "provider_reference": "build-request-41"
  },
  "decision": "allow"
}

Depois dessa reserva, restam 350 centavos para todas as outras ações da execução. Se a cobrança real for de 620 centavos, libere 230 centavos. Se for de 910 centavos, registre o excesso, negue os gastos posteriores e investigue por que a estimativa falhou. Não permita que o agente tome emprestado livremente de um orçamento futuro porque o número final foi inconveniente.

Alguns provedores mostram o preço na solicitação ou retornam uma estimativa de uso antes do início do trabalho. Use-a. Outros não fazem isso. Para esses serviços, classifique as ações por risco. Permita uma leitura barata dentro do orçamento normal de solicitações. Exija aprovação explícita para uma ação que possa criar um recurso sem limite, enviar mensagens pagas, fazer um pedido ou iniciar um trabalho cujo custo não possa ser limitado.

Equipes muitas vezes rejeitam reservas porque as estimativas são imperfeitas. Esse argumento confunde precisão contábil com controle. Uma porta corta-fogo não precisa calcular exatamente o calor do incêndio antes de fechar. Uma reserva conservadora pode rejeitar uma tarefa que caberia no orçamento, mas o agente pode solicitar uma alocação maior com contexto. Isso é melhor do que descobrir uma cobrança sem limite depois que o agente desapareceu.

Mantenha créditos do provedor e cotas de toda a organização fora do orçamento da execução. Eles são redes de segurança, não substitutos. Uma cota mensal normalmente permite que uma única execução consuma muito mais do que sua tarefa merece.

Novas tentativas precisam de uma margem menor que as primeiras tentativas

Novas tentativas devem ser raras, limitadas e classificadas conforme repetir a solicitação possa repetir o efeito colateral. Uma instrução genérica para repetir erros é o que transforma uma interrupção temporária em um padrão caro de tráfego.

A RFC 9110 define métodos idempotentes, como GET, PUT e DELETE, em termos do efeito pretendido no servidor. Ela também diz que um cliente não deve repetir automaticamente uma solicitação não idempotente, a menos que saiba que repetir é seguro. Essa ressalva importa ainda mais com agentes do que com código comum de aplicações: o agente pode alterar o corpo entre tentativas, decidir que uma resposta anterior estava incompleta e enviar o que parece ser uma solicitação nova.

A RFC 6585 define o HTTP 429, Too Many Requests, e diz que uma resposta pode incluir Retry-After. Respeite esse cabeçalho quando ele estiver presente. Não o trate como permissão para dormir até seu vencimento e depois continuar para sempre. A nova tentativa ainda consome o orçamento de tempo da execução, e a tarefa original pode já não justificar a espera.

Use um registro de novas tentativas que responda a quatro perguntas antes de cada repetição: o que falhou, se a ação remota pode ter ocorrido, quanto tempo esperar e qual orçamento pagará por outra tentativa. Uma política prática é:

request_classes:
  read:
    max_attempts: 3
    retry_on: [408, 429, 502, 503, 504]
    backoff_seconds: [2, 8]
  idempotent_write:
    max_attempts: 2
    require_idempotency_token: true
    retry_on: [408, 429, 503]
  non_idempotent_write:
    max_attempts: 1
    retry_on: []

Essa política evita uma falha conhecida. O agente envia POST /invoices e perde a conexão antes de receber uma resposta. Uma repetição descuidada pode criar uma segunda fatura. Um token de idempotência permite que um provedor compatível reconheça a duplicata, mas somente se o agente reutilizar o mesmo token e exatamente a mesma operação lógica. Se o agente alterar o valor, o cliente ou o token na segunda tentativa, a proteção deixa de valer.

Para uma ação não idempotente, prefira uma consulta de status usando um identificador de operação gerado pelo cliente. Se o provedor não oferecer idempotência nem consulta de status, trate um tempo limite ambíguo como caso que exige revisão humana. Isso parece mais lento que repetir automaticamente, até que alguém precise desfazer transferências, pedidos ou mensagens duplicados.

O jitter importa quando muitos agentes enfrentam a mesma interrupção. Use um intervalo aleatório para que eles não tentem novamente ao mesmo tempo. Mantenha a programação curta o bastante para que o prazo da execução continue significativo. Um intervalo exponencial de seis horas pode proteger o provedor, mas manter uma sessão do agente aberta muito depois de a tarefa deixar de importar.

Loops de consulta precisam de um limite próprio

Um agente que espera por um trabalho assíncrono deve receber uma franquia explícita para consultas, porque os limites normais de solicitações escondem esse padrão até que ele já esteja caro. Consultar tem uma finalidade legítima, mas precisa de um intervalo, uma quantidade máxima de verificações e um prazo que pertença à operação.

A versão ruim é fácil de reconhecer nos logs:

14:00:03 POST /exports                 202 accepted
14:00:04 GET  /exports/ea91            202 running
14:00:05 GET  /exports/ea91            202 running
14:00:06 GET  /exports/ea91            202 running
...
14:11:58 GET  /exports/ea91            202 running

O agente interpretou “ainda em execução” como uma instrução para perguntar de novo. Isso não é persistência. É uma política ausente.

Comece pelas orientações documentadas do provedor. Se um endpoint retornar Retry-After, respeite-o dentro do prazo restante. Se retornar um horário estimado de conclusão, não faça consultas antes desse momento. Se oferecer um webhook ou callback, use-o em vez de manter a execução do agente aberta. Um callback externo pode retomar um fluxo controlado mais tarde; não deve ressuscitar uma execução expirada com a autoridade antiga.

O orçamento de consultas também deve distinguir o estado do trabalho de uma falha de transporte. 202 running informa que o trabalho existe. Um tempo limite não informa se a consulta de status chegou ao destino. Não use a mesma permissão de repetição para os dois casos. O primeiro pode esperar até a próxima verificação agendada. O segundo pode justificar uma nova tentativa, sujeita ao limite normal.

Defina uma ação terminal para uma franquia de consultas expirada: registre o último estado conhecido, preserve o identificador da operação remota e devolva uma instrução de retomada. Não cancele automaticamente, a menos que a tarefa original diga que o cancelamento é seguro. Alguns trabalhos deixam um resultado utilizável depois que o agente desiste de esperar, e algumas solicitações de cancelamento têm seus próprios efeitos colaterais.

Esse desenho torna o trabalho atrasado visível para uma pessoa. “A exportação ainda está em execução após seis verificações; a operação ea91 pode ser verificada mais tarde” é uma transferência útil. “Agente concluído” depois de um loop oculto em segundo plano não é.

O prazo deve incluir esperas, ferramentas e tempo na fila

O prazo da execução deve medir todo o período em que o agente pode causar trabalho externo. Ele precisa incluir o raciocínio do modelo entre chamadas, o sono das novas tentativas, a execução de ferramentas locais, a espera na fila, travamentos de DNS e o tempo aguardando uma aprovação. Um cronômetro apenas ao redor do cliente HTTP deixa grandes lacunas nas quais um loop pode continuar.

Use um cronômetro monotônico de tempo transcorrido para aplicar esse limite. Relógios civis podem saltar quando um laptop dorme, retorna ou recebe uma correção de horário. Armazene carimbos de horário civil para auditoria, mas calcule a expiração com uma duração transcorrida que não retrocede.

Passe o tempo restante para todas as operações. Se faltam 40 segundos para o fim da execução, ela não deve iniciar uma solicitação HTTP com tempo limite de 90 segundos nem chamar um comando SSH sem tempo limite. A operação filha recebe o menor valor entre seu limite local e a duração restante da execução.

remaining = run_deadline_monotonic - now_monotonic
if remaining <= 0:
    deny("run_deadline_exhausted")
else:
    operation_timeout = min(remaining, endpoint_timeout)
    execute(operation_timeout)

Trate as esperas por aprovação com cuidado. Uma pessoa pode responder em cinco minutos, mas a execução do agente pode ter apenas 30 segundos restantes. Quando a aprovação chegar depois da expiração, negue a ação e mostre o motivo. Permitir que a aprovação reanime uma execução expirada cria uma brecha: o agente pode enfileirar ações caras antes do prazo e executá-las mais tarde enquanto alguém clica nos cartões.

Tarefas longas precisam de outro formato. Divida-as em pontos de verificação com novos orçamentos e uma transição de estado registrada. Por exemplo, um agente pode enviar uma exportação em uma execução e uma execução posterior pode verificar a exportação concluída e decidir o que fazer com ela. Cada execução recebe uma finalidade, um conjunto pequeno de autoridades e um horário claro de término. Isso é menos mágico que uma sessão imortal do agente, exatamente por ser mais fácil de auditar.

Limites de escopo impedem gastos no lugar errado

Um orçamento responde quanto de atividade externa uma execução pode realizar. O escopo responde onde e no que ela pode tocar. Sem escopo, o agente pode gastar uma franquia perfeitamente razoável sondando hosts sem relação, seguindo um link envenenado ou escolhendo um endpoint caro que nunca fez parte da tarefa.

Defina o escopo em termos concretos: hosts aprovados, identidades de credenciais, métodos HTTP, destinos SSH, caminhos ou famílias de comandos permitidos e tamanho máximo do corpo da solicitação. Mantenha a definição estreita o bastante para que um revisor a entenda. Não tente escrever uma pequena linguagem de programação para cada condição possível. Sistemas de políticas complexos acumulam exceções até que ninguém consiga prever seu resultado sob pressão.

A diferença entre uma fronteira de credenciais e uma fronteira de orçamento importa. A fronteira de credenciais decide se o agente pode usar um segredo para chamar um serviço. A fronteira de orçamento decide se essa execução pode fazer outra chamada depois de receber essa permissão. Equipes frequentemente instalam a primeira e presumem que ela oferece a segunda. Não oferece. Um token de API perfeitamente protegido ainda pode financiar mil solicitações desnecessárias.

Para HTTP, rejeite redirecionamentos que saiam do conjunto de hosts aprovados, a menos que uma pessoa tenha permitido explicitamente o destino. O tratamento de redirecionamentos é fácil de ignorar porque muitos clientes os seguem automaticamente. Uma solicitação que começa em uma URL aprovada pode terminar em outro host, levando cabeçalhos ou consumindo orçamento em um serviço que a tarefa nunca mencionou.

Para SSH, evite dar ao agente um shell geral apenas porque o primeiro trabalho envolve um comando. Restrinja o destino e a interface de comandos quando possível. Defina um tempo limite e conte cada tentativa de conexão. Um loop de conexões malsucedidas continua sendo atividade externa, mesmo sem autenticação.

Separe escopos de leitura e escrita. Uma tarefa de coleta de dados pode precisar de vários endpoints de leitura e não ter permissão para criar registros. Uma tarefa de alteração pode precisar de um endpoint de escrita e de uma leitura preliminar restrita. Essa divisão torna o orçamento mais útil, porque a contagem de solicitações sozinha não distingue repetição inofensiva de efeitos colaterais repetidos.

As negações precisam deixar evidências suficientes para reconstruir o loop

Uma parada por orçamento só é útil se puder ser explicada depois. Registre cada decisão antes do início da chamada externa, o resultado depois que ela terminar e as negações com o mesmo cuidado dado às chamadas bem-sucedidas. Caso contrário, um evento ausente pode parecer uma solicitação bloqueada.

Use um único identificador imutável de execução em mensagens do modelo, ferramentas locais, solicitações HTTP, conexões SSH, aprovações e registros de auditoria. Cada tentativa externa deve incluir um número de sequência. Se houver uma repetição, vincule-a à operação lógica original e informe se a ação foi idempotente, ambígua ou confirmadamente inexistente.

Um registro compacto contém o suficiente para investigar sem armazenar dados sensíveis:

{
  "run_id": "run_7c1f",
  "attempt": 17,
  "logical_operation": "fetch_export_status:ea91",
  "channel": "http",
  "destination_class": "approved-export-api",
  "outcome": "denied",
  "reason": "poll_allowance_exhausted",
  "attempts_remaining": 0,
  "elapsed_ms": 598244,
  "reserved_spend_cents": 0
}

Não registre tokens bearer, senhas, chaves privadas ou corpos completos de solicitações por padrão. Uma auditoria de orçamento precisa de identificadores, classes, hashes quando forem úteis e contexto da decisão. Ela não precisa de um segundo cofre de segredos cheio das mesmas credenciais que você tentou proteger.

Torne a sequência de eventos resistente a adulteração. Uma cadeia de hashes faz cada registro depender do anterior, de modo que a remoção ou alteração quebre a verificação. Quando possível, armazene o material de verificação separado do agente em execução. Um agente que pode escrever seu próprio histórico não pode conseguir editar o registro que prova que excedeu o orçamento.

O Sallyport registra sessões de agentes e chamadas individuais em um log de auditoria criptografado, encadeado por hash e sem permissão de escrita pelo agente; o comando sp audit verify pode verificar a cadeia offline sobre o texto cifrado. Esse desenho é útil para aplicar orçamentos porque uma ação negada continua fazendo parte das evidências, em vez de desaparecer como uma decisão interna.

A aprovação humana deve ficar nas exceções, não em cada leitura

A aprovação humana deve lidar com mudanças de consequência ou escopo que um orçamento numérico não consegue avaliar. Ela não deve virar um carimbo para chamadas rotineiras. Se uma pessoa vir um cartão de aprovação para cada solicitação, aprovará o décimo aviso com a mesma atenção dada ao primeiro.

Peça aprovação quando uma ação criar um novo beneficiário, gastar além da reserva, escrever em um sistema de produção, enviar uma comunicação visível externamente, alterar o conjunto de destinos aprovados ou retomar o trabalho depois de uma mudança relevante na entrada da tarefa. A aprovação deve mostrar a ação em linguagem simples, o destino, o impacto no orçamento e a identidade do processo que a solicita.

Não trate a aprovação como cura para um orçamento fraco. Uma pessoa distraída pode autorizar uma ação ruim, e uma execução sem supervisão talvez nunca receba resposta. O orçamento ainda precisa expirar enquanto a aprovação espera. Se a tarefa continuar valendo a pena, a pessoa pode conceder uma nova alocação para uma nova execução.

Evite pedir que as pessoas aprovem “continuar” sem contexto. Continuar o quê? Contra qual serviço? Com qual cobrança estimada? Quantas chamadas a execução já fez? Uma boa solicitação de aprovação torna esses fatos visíveis. Um pedido vago leva o revisor a confiar no resumo do agente, justamente a parte que tem interesse em continuar trabalhando.

Há uma divisão de responsabilidades útil. O gateway aplica limites fixos de maneira consistente. A pessoa decide se uma ação excepcional tem valor suficiente para justificar mais autoridade. Mantenha essas responsabilidades separadas para que nenhuma precise fingir que resolve o trabalho da outra.

O esgotamento do orçamento deve gerar uma transferência retomável

Quando um limite interrompe uma execução, o agente deve devolver um pequeno registro de estado que permita a uma pessoa ou a uma execução posterior continuar com segurança. Uma mensagem de erro vaga incentiva alguém a repetir a tarefa inteira, refazendo chamadas concluídas e possivelmente repetindo efeitos colaterais.

A transferência precisa conter o objetivo da tarefa, os identificadores das operações concluídas, o trabalho remoto pendente, o motivo exato da parada e uma recomendação para a próxima alocação. Ela deve informar se repetir é seguro. Nunca deve esconder que uma ação terminou em estado ambíguo.

Por exemplo:

Parado: o orçamento de tempo transcorrido se esgotou.
Concluído: trabalho de exportação ea91 enviado; nenhum arquivo baixado.
Último estado observado: em execução às 14:09:58 UTC.
Tentativas externas: 14 de 14; gasto reservado: 0 centavos.
Retomada segura: verificar o status de ea91 uma vez depois de 14:20 UTC.
Ação insegura: não enviar outra solicitação de exportação.

Essa mensagem evita a forma mais cara de recuperação: começar de novo porque ninguém sabe o que aconteceu. Ela também torna possível ajustar os orçamentos. Se muitas execuções normais terminam depois de uma única verificação de status, a duração permitida é curta demais. Se as execuções costumam consumir toda a franquia em pesquisas sem progresso, a divisão da tarefa ou o escopo estão errados.

Não reponha automaticamente um orçamento esgotado. Uma regra de reposição é apenas um orçamento ilimitado escrito em parcelas menores, a menos que uma autoridade separada decida quando ela se aplica. Exija uma nova execução ou uma ação humana explícita, preserve o registro antigo e faça a próxima tentativa explicar por que merece mais espaço.

A primeira política que vale a pena aplicar é simples: toda execução autônoma recebe uma quantidade finita de solicitações, um prazo rígido e uma reserva de gastos antes de chegar a um serviço externo. Acrescente restrições de escopo e bons registros logo depois. Quando o agente aprende que não pode tentar para sempre, suas falhas se tornam itens de trabalho contidos, em vez de incidentes durante a noite.