Einem KI-Agenten Live-Websuche geben, mit hartem Ausgabenlimit

Einem Modell ein Such-Tool zu geben, sind vier Zeilen Code. Ihm ein Such-Tool zu geben, das dich nicht über Nacht 4.000 Dollar kosten kann, braucht etwas mehr Überlegung.

Der Fehlermodus ist konkret: ein Agent, der bei leeren Ergebnissen immer wieder von vorn anfängt, oder eine Frage in vierzig Unterabfragen zerlegt, oder in einer Planen-Suchen-Neuplanen-Schleife hängen bleibt. Nichts davon sieht aus wie ein Bug, während es passiert. Es sieht aus wie ein Agent, der hart arbeitet.

Verlass dich beim Budget nicht auf den Prompt

„Nutze maximal 5 Suchen” in einem System-Prompt ist eine Präferenz, kein Limit. Sie verliert bei langen Kontexten an Wirkung, wird von einem selbstbewussten Plan überschrieben und verschwindet komplett, sobald der Agent eine wirklich schwere Frage bekommt.

Ausgabenlimits gehören an drei Stellen, mit denen das Modell nicht diskutieren kann.

Ebene 1: ein Guthaben, das das Modell nicht überschreiten kann

Das äußerste Limit sollte der Key selbst sein. Ein Key mit einem endlichen Guthaben kann nicht mehr ausgeben, als dieses Guthaben hergibt, egal was der Agent entscheidet. Bei FastAF liegt das Guthaben auf dem Account, und jeder Request reserviert seine Kosten, bevor die Arbeit beginnt, sodass eine außer Kontrolle geratene Schleife auf 402 insufficient_credits läuft und stoppt.

Das Guthaben gehört zum Konto, und alle Keys dieses Kontos zehren davon. Keys dienen dazu, Zugriff zu entziehen (einer pro Deployment, damit ein geleakter Key allein gesperrt werden kann), nicht dazu, Geld aufzuteilen: Wenn ein Nebenprojekt das Budget deiner Produktionspipeline nicht leerräumen darf, gib ihm ein eigenes Konto mit eigenem, bewusst aufgeladenem Guthaben.

Ebene 2: ein Budget pro Lauf im Tool-Wrapper

Innerhalb eines einzelnen Laufs zählst du mit, was du ausgibst, und verweigerst weitere Anfragen danach. Jede Antwort trägt ihre Kosten in einem Header, die Abrechnung ist also exakt statt geschätzt:

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:
            # Wird dem Modell als normales Tool-Ergebnis zurückgegeben, nicht als
            # Exception: der Agent soll über das aufgebrauchte Budget nachdenken können.
            return {"error": "search budget exhausted for this run"}

        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": "out of credits"}
        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,
        }

Geprüft wird spent + cost > max_credits, nicht nur spent: Bei einem Budget von 6 ließe die Prüfung von spent allein eine zweite Suche mit 5 Credits durch, insgesamt also 10.

Zwei Details zählen mehr, als es aussieht. Erstens: Das Aufbrauchen des Budgets kommt als Tool-Ergebnis zurück, nicht als Exception, damit sich der Agent anpassen und mit dem antworten kann, was er hat, statt den Lauf abstürzen zu lassen. Zweitens: Dem Modell zu zeigen, wie viel Budget noch übrig ist, verändert sein Verhalten messbar. Agenten, die ein schrumpfendes Budget sehen, priorisieren ihre Abfragen.

Ebene 3: kürze, was zurück in den Kontext geht

Eine rohe SERP-Antwort ist groß, und sie komplett in den Kontext zu schieben, kostet mehr an Tokens, als die Suche an Credits gekostet hat. Die Top 5 Ergebnisse mit Titel, Link und Snippet zurückzugeben, reicht dem Modell fast immer, um zu entscheiden, was es vollständig lesen will, und hält die Schleife günstig.

Das ist auch der Grund, warum „suchen” und „Seite abrufen” zwei getrennte Tools sein sollten: Lass das Modell günstig suchen und die volle Seite nur für die zwei oder drei Links bezahlen, die es wirklich will.

Ebene 4: die Nebenläufigkeit begrenzen

Wenn dein Agent Unterabfragen parallel auffächert, deckel den Fan-out auf oder unter dem Concurrency-Limit deines Plans. Darüber bekommst du 429-Antworten mit einem Retry-After-Header, den eine naive Retry-Schleife in eine Flut duplizierter Requests verwandelt. Respektiere den Header, und halte den Worker-Pool klein.

Wohin das führt

Heute ist der saubere Weg ein REST-Aufruf mit einem eingeschränkten Key und einem Budget, das du im Wrapper durchsetzt, genau das, was der Code oben macht. Der andere Weg ist, dass der Agent jeden Aufruf selbst bezahlt, ganz ohne Account. FastAF unterstützt x402 schon heute auf jedem REST-Endpoint, zu 0,001 USDC pro Credit auf Base: Eine Google-Suche kostet 0,005 $ und wird nur abgerechnet, wenn der Aufruf klappt (MPP wird nicht unterstützt). Das Limit ist dann das Guthaben der Wallet, während Prepaid-Credits bei Volumen günstiger bleiben. Die x402-Docs zeigen den ganzen Ablauf.

Die Docs enthalten die vollständige Endpoint-Liste und die Fehler-Semantik, und die Preise zeigen die Credit-Kosten jedes Aufrufs, damit du ein Budget pro Lauf sauber dimensionieren kannst.