# Como definir um limite rígido de gastos para uma tarefa de agente de programação? > Um limite rígido deve ser aplicado antes de cada chamada de modelo ou ferramenta paga por um gateway que controla o orçamento da tarefa. Reserve o custo máximo, concilie o uso real, rejeite chamadas que não caibam e encerre o agente com um checkpoint útil. # Como definir um limite rígido de gastos para uma tarefa de agente de programação? Um orçamento rígido é controle de admissão. Antes de qualquer chamada cobrável, um gateway confiável deve provar que o pior custo permitido cabe no saldo restante. Alertas posteriores não impedem um excesso já ocorrido. O projeto deve incluir entrada, saída máxima, tentativas, fallbacks, subagentes, embeddings, buscas, sandboxes e toda ferramenta paga. ## Separe limites rígidos de metas flexíveis Use três valores: | Controle | Objetivo | Comportamento | |---|---|---| | Meta | Custo esperado | Alertar ou escolher plano mais barato | | Limite flexível | Ponto de escalada | Pedir aprovação ou reduzir qualidade | | Limite rígido | Gasto máximo autorizado | Rejeitar antes da próxima chamada | Por exemplo: meta de $0.60, aprovação em $0.90 e parada em $1.00. O limite rígido deve estar no servidor, não só no prompt. ## Passe toda ação paga por um gateway Dê ao agente credenciais curtas que só chamem seu gateway. Ele anexa `task_id`, consulta o orçamento, estima a ação e reserva ou rejeita. Não exponha chave que permita ignorar a contabilidade. Aplique a mesma regra a busca, sandbox, execução e recuperação paga. ## Reserve antes e concilie depois Estime o limite com tokens de entrada e saída máxima. Reserve atomicamente, faça a chamada e substitua a reserva pelo uso real. ```text remaining = hard_limit - committed_cost - open_reservations worst_case = input_cost + max_output_cost + tool_allowance if worst_case > remaining: reject("task_budget_exceeded") else: reserve(worst_case) call_provider() reconcile(actual_cost) ``` A reserva atômica impede dois subagentes de gastar o mesmo saldo. ## Use uma tabela de preços versionada Guarde a tarifa usada em cada estimativa. Preços mudam e relatórios futuros não devem recalcular o passado com a tarifa atual. Se o provedor devolver custo final, preserve estimativa e cobrança. Se devolver apenas tokens, use a versão escolhida antes da chamada. Acrescente margem para ferramentas incertas ou rejeite o que não puder limitar. ## Torne o streaming seguro Reserve toda a saída permitida antes de abrir o stream. Concilie uso quando disponível, mas não suponha que fechar o cliente encerra imediatamente a cobrança. Cancelamento é otimização, não a fronteira de controle. Defina limite por chamada e timeout. O teto da tarefa ainda cobre streams, tentativas e fallbacks. ## Inclua tentativas e subagentes Toda tentativa debita o mesmo ledger pai. Uma nova tentativa com orçamento novo anula o limite. Use orçamentos hierárquicos: | Ledger | Limite | Regra | |---|---:|---| | Tarefa pai | $1.00 | Teto absoluto | | Subagente de implementação | $0.55 | Não supera o saldo pai | | Subagente de testes | $0.25 | Devolve reserva não usada | | Revisão final | $0.20 | Só roda se houver saldo | Limites filhos são alocações, não dinheiro extra. ## Pare com um checkpoint útil Quando a ação não couber, devolva erro tipado. O agente não deve repetir a chamada rejeitada. Gere um checkpoint com o contexto existente contendo: * alterações concluídas e testes; * trabalho restante e ação bloqueada; * estado atual do repositório; * orçamento adicional estimado; * token de retomada ou ID da tarefa. Assim, a parada vira uma entrega controlada. ## Use controles do provedor como proteção Limites de conta reduzem o impacto, mas raramente são precisos por tarefa. Podem misturar repositórios, atualizar tarde ou omitir ferramentas. Com um gateway multimodelo como Atlas Cloud, mantenha o ledger autoritativo na sua orquestração e registre IDs de uso para conciliação. O limite persiste mesmo ao trocar de modelo. ## Teste o limite como controle financeiro Teste concorrência, streams longos, timeouts, uso ausente, tentativas, fallbacks e falhas do ledger. Se o serviço orçamentário falhar, negue por padrão. Custos mais reservas nunca podem exceder o teto. ## Em resumo Um limite real é aplicado antes do gasto, com reservas atômicas e um ledger para toda ação cobrável. Se o sistema só avisa depois, é monitoramento, não limite rígido. ## FAQ ### max_tokens é um limite rígido em dinheiro? Não. Ele limita uma resposta, não o custo total, tokens de entrada, novas tentativas, troca de modelo ou ferramentas. Um limite monetário exige um ledger para toda ação cobrável. ### Onde o orçamento do agente deve ser aplicado? Em um gateway ou camada de orquestração no servidor por onde passem todas as chamadas de modelos e ferramentas pagas. Contadores no cliente podem ser ignorados ou sofrer condições de corrida. ### Como orçar respostas em streaming? Reserve o custo máximo permitido antes de abrir o stream e concilie com o uso informado ao fechar. Cancele no provedor quando houver suporte, mas não dependa apenas disso. ### Novas tentativas compartilham o orçamento original? Sim. Tentativas, fallbacks, subagentes e avaliações devem debitar o mesmo ledger, salvo aprovação explícita de outro orçamento. ### O que acontece quando o saldo é insuficiente? Rejeite a próxima chamada cobrável e peça ao agente um checkpoint usando o contexto disponível, com trabalho concluído, pendências e o orçamento adicional necessário. ### Limites da conta do provedor substituem o limite por tarefa? Em geral, não. Eles protegem a conta inteira e podem atualizar de forma assíncrona. Um gateway por tarefa isola imediatamente; o limite da conta serve como proteção adicional.