Dê a um agente de IA busca na web ao vivo com um teto de gastos rígido

Dar a um modelo uma ferramenta de busca é questão de quatro linhas de código. Dar a ele uma ferramenta de busca que não possa custar $4.000 da noite para o dia exige um pouco mais de cuidado.

O modo de falha é específico: um agente que insiste em resultados vazios, ou decompõe uma pergunta em quarenta subconsultas, ou fica preso em um ciclo de planejar-buscar-replanejar. Nada disso parece um bug enquanto acontece. Parece o agente trabalhando duro.

Não confie no prompt para controlar o orçamento

“Use no máximo 5 buscas” em um system prompt é uma preferência, não um limite. Ele se degrada em contextos longos, é ignorado por um plano confiante e desaparece por completo assim que o agente recebe uma pergunta genuinamente difícil.

Limites de gasto precisam ficar em lugares com os quais o modelo não pode discutir.

Camada 1: um saldo de créditos que o modelo não pode ultrapassar

O limite mais externo deve ser a própria chave. Uma chave com saldo finito não pode gastar mais do que esse saldo, seja lá o que o agente decidir fazer. Na FastAF o saldo fica na conta e cada requisição reserva seu custo antes de o trabalho começar, então um loop descontrolado esbarra em 402 insufficient_credits e para.

O saldo pertence à conta, e todas as chaves dessa conta usam o mesmo saldo. Chaves servem para revogar acesso (uma por implantação, para cortar sozinha uma chave vazada), não para dividir dinheiro: se um projeto paralelo não pode drenar o orçamento do seu pipeline de produção, dê a ele uma conta própria com saldo próprio, recarregado de forma deliberada.

Camada 2: um orçamento por execução no wrapper da ferramenta

Dentro de uma única execução, conte o que você gasta e recuse-se a ir além. Toda resposta traz seu custo em um header, então a contabilidade é exata, não estimada:

import requests

class SearchBudget:
    cost = 5  # credits per search

    def __init__(self, api_key, max_credits=100):
        self.api_key = api_key
        self.max_credits = max_credits
        self.spent = 0

    def search(self, query, country="us"):
        if self.spent + self.cost > self.max_credits:
            # Devolvido ao modelo como um resultado normal da ferramenta, não como
            # exceção: o agente deve conseguir raciocinar sobre ficar sem orçamento.
            return {"error": "orçamento de busca esgotado para esta execução"}

        response = requests.get(
            "https://api.fastaf.co/v1/serp",
            params={"query": query, "country": country},
            headers={"Authorization": f"Bearer {self.api_key}"},
            timeout=60,
        )

        if response.status_code == 402:
            return {"error": "sem créditos"}
        if response.status_code != 200:
            return {"error": response.json().get("error", {}).get("code", "search_failed")}

        self.spent += int(response.headers.get("X-FastAF-Credits-Used", 5))
        data = response.json()
        return {
            "results": [
                {"title": r["title"], "link": r["link"], "snippet": r.get("snippet")}
                for r in data.get("organic_results", [])[:5]
            ],
            "credits_remaining": self.max_credits - self.spent,
        }

A checagem é spent + cost > max_credits, não apenas spent: com um orçamento de 6, checar só spent deixaria passar uma segunda busca de 5 créditos, 10 no total.

Dois detalhes importam mais do que parecem. Primeiro, o esgotamento volta como resultado da ferramenta em vez de ser lançado como uma exceção, então o agente pode se adaptar e responder com o que já tem, em vez de derrubar a execução. Segundo, informar ao modelo quanto orçamento resta muda o comportamento dele de forma mensurável: agentes que enxergam um orçamento diminuindo priorizam suas consultas.

Camada 3: reduza o que volta para o contexto

Uma resposta SERP bruta é grande, e jogar tudo isso no contexto custa mais em tokens do que a busca custou em créditos. Devolver os cinco primeiros resultados com título, link e snippet quase sempre é suficiente para o modelo decidir o que ler por completo, e mantém o loop barato.

É também por isso que “buscar” e “baixar a página” deveriam ser duas ferramentas separadas: deixe o modelo buscar barato e pague pela página completa só para os dois ou três links que ele realmente quer.

Camada 4: limite a concorrência

Se o seu agente dispara subconsultas em paralelo, limite esse fan-out no valor do limite de concorrência do seu plano, ou abaixo dele. Acima disso você recebe respostas 429 com um header Retry-After, que um loop de retry ingênuo transforma em uma rajada de requisições duplicadas. Respeite o header e mantenha o pool de workers pequeno.

Para onde isso está indo

Hoje, a forma mais limpa de montar isso é uma chamada REST com uma chave com escopo definido e um orçamento imposto no wrapper, que é exatamente o que o código acima faz. O outro caminho é o próprio agente pagar cada chamada, sem conta nenhuma. O FastAF já suporta x402 hoje em todos os endpoints REST, a 0,001 USDC por crédito na Base: uma busca no Google custa US$ 0,005 e só é cobrada se a chamada der certo (MPP não é suportado). O teto passa a ser o saldo da wallet, enquanto em volume os créditos pré-pagos continuam mais baratos. A documentação do x402 mostra o fluxo completo.

A documentação tem a lista completa de endpoints e a semântica de erros, e os preços têm o custo em créditos de cada chamada para você dimensionar corretamente um orçamento por execução.