KI-Agent Kontextfenster: Überladene API-Antworten optimieren

Der Agent fragt nach einem Kundendatensatz. Ihre API gibt den Kunden zurück, plus dessen letzte 200 Bestellungen, plus jeden einzelnen Posten dieser Bestellungen, plus Zeitstempel in drei Formaten und einen _links-Block für jeden. Vierzigtausend Token landen im Kontextfenster. Der Agent benötigte die E-Mail-Adresse.

Machen Sie das viermal in einem Durchlauf, und der Agent hat den größten Teil seines Budgets damit verbracht, JSON zu lesen, das er nicht angefordert hat. Dann beginnen die interessanten Fehler: Er vergisst die ursprüngliche Anweisung, er fasst die Aufgabe zusammen, anstatt sie zu beenden, und die Kosten pro Durchlauf steigen, während die Qualität sinkt.

Dies ist ein Designproblem auf der API-Ebene, kein Prompt-Problem. Agenten verbrauchen Antworten über ein festes Fenster, und jedes Feld, das Sie zurückgeben, konkurriert mit den Anweisungen, der Konversation und dem Plan. Dieser Leitfaden behandelt, woher die Überladung kommt, die Feld-Auswahl- und Paginierungsmuster, die sie beheben, wie man innerhalb der Tool-Ebene trimmt, wenn man die API nicht kontrolliert, und wie man den Unterschied misst. Unser Artikel über warum KI-Agenten in der Produktion versagen behandelt die Kontexterschöpfung als eine der zentralen Fehlerursachen, und dies ist die praktische Hälfte davon.

Apidog hilft bei der Messung: Sie können die tatsächliche Antwortgröße für jeden Endpunkt sehen, bevor ein Agent ihn jemals aufruft, und die gewünschte gekürzte Form modellieren, bevor das API-Team sie liefert.

Wohin die Tokens gehen

Antworten, die für Browser und Dashboards konzipiert sind, enthalten viele Daten, die einen Agenten echtes Geld kosten.

Ausführliche Umschläge. Ein data-, meta-, links-, included-Wrapper um ein Objekt mit fünf Feldern kann die Nutzlast verdoppeln. Hypermedia-Links sind nützlich für einen Client, der ihnen folgt. Agenten tun das fast nie, und jede URL sind Tokens.

Wiederholte Schlüssel. JSON wiederholt jeden Feldnamen bei jedem Array-Element. Eine Liste mit 200 Elementen und 15 Feldern pro Element zahlt für 3.000 Schlüssel-Strings. Deshalb dominieren Listenendpunkte die Kontextnutzung.

Verschachtelte Erweiterung standardmäßig. Endpunkte, die verwandte Ressourcen inline einbetten, sind praktisch, bis ein Agent sie trifft. Ein Kunde plus seine Bestellungen plus Artikel ist ein Baum, und Bäume wachsen schnell.

Redundante Formate. created_at, created_at_unix und created_at_human auf demselben Objekt sind dreifache Kosten für einen Wert.

Nullwerte und leere Felder. Viele Serializer geben jedes Feld aus, auch wenn es nicht gesetzt ist. Zwanzig null-Werte pro Datensatz sind reine Verschwendung.

Eine nützliche Sichtweise: Die Token-Kosten verfolgen die Größe des serialisierten Textes, nicht die Anzahl der Datensätze. Zweihundert Datensätze mit jeweils fünf Feldern können günstiger sein als ein einziges tief verschachteltes Objekt.

Regel eins: Felder zurückgeben, nicht Ressourcen

Die wertvollste einzelne Änderung besteht darin, dem Aufrufer zu ermöglichen, genau das anzufordern, was er benötigt.

GET /v1/customers/8812?fields=id,email,plan,status

{ "id": "8812", "email": "dana@example.com", "plan": "pro", "status": "active" }

Das ist eine 90-prozentige Reduzierung gegenüber einem vollständigen Datensatz bei den meisten APIs und erfordert einen Nachmittag zur Implementierung. Googles API-Designhandbuch dokumentiert das Field-Mask-Muster, wenn Sie eine Version mit Präzedenzfall wünschen, und GraphQL löst dasselbe Problem, indem es die Auswahl obligatorisch macht.

Zwei Implementierungshinweise. Validieren Sie die Feldliste gegen das Schema und lehnen Sie unbekannte Namen ab, damit ein halluziniertes Feld einen klaren Fehler anstelle eines stillschweigend gekürzten Objekts erzeugt. Und halten Sie einen kleinen Standardsatz für Aufrufer vor, die nichts senden, anstatt standardmäßig alles zurückzugeben.

Dann exponieren Sie den Parameter im Tool-Beschreibung für das Modell, mit den explizit aufgelisteten Feldern:

{
  "name": "getCustomer",
  "description": "Fetch a customer by ID. Always pass `fields` with only what you need. Available: id, email, name, plan, status, created_at, billing_address, order_count.",
  "input_schema": {
    "type": "object",
    "required": ["customerId", "fields"],
    "properties": {
      "customerId": { "type": "string" },
      "fields": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Field names to return. Keep this list minimal."
      }
    }
  }
}

Beschreibungen sind der einzige Ort, an dem das Modell diese Regeln lernt, und sowohl der OpenAI-Leitfaden für Funktionsaufrufe als auch die Anthropic-Dokumentation zur Tool-Nutzung legen das gleiche Gewicht darauf. Das Erfordernis von fields ist der Trick. Ein optionaler Parameter wird übersprungen; ein erforderlicher zwingt das Modell dazu, darüber nachzudenken, was es tatsächlich benötigt.

Regel zwei: Listen immer begrenzen

Unbegrenzte Listenendpunkte sind die zweite große Quelle für Explosionen. Ein Agent fragt nach „letzten Bestellungen“ und erhält alles seit 2019.

Legen Sie ein festes serverseitiges Maximum fest, nicht nur einen Standardwert. Wenn der Agent limit=5000 sendet, geben Sie 100 zurück und teilen Sie dies mit. Unsere Leitfäden zur REST API-Paginierung und zum Design von Paginierung für Millionen von Datensätzen behandeln die Mechanik; die agentspezifischen Regeln sind enger gefasst:

• Begrenzen Sie die Seite auf etwas, das ein Modell lesen kann, im Bereich von 20 bis 50 Elementen für typische Datensätze.
• Geben Sie eine Gesamtzahl zurück, damit der Agent feststellen kann, ob er alles gesehen hat, ohne durch Blättern nachsehen zu müssen.
• Verwenden Sie Cursor-Paginierung. Offsets verschieben sich, wenn sich Daten während des Durchlaufs ändern, und ein Agent, der langsam paginiert, wird darauf stoßen.
• Fügen Sie eine klare Aussage in die Antwort ein, z. B. "truncated": true, damit das Modell weiß, dass es mehr gibt. Modelle schätzen die Vollständigkeit allein anhand der Array-Länge oft falsch ein.

Geben Sie dem Agenten auch eine Möglichkeit, die Paginierung ganz zu vermeiden. Ein count-Endpunkt, eine gefilterte Suche mit einem engen Fenster oder ein Übersichts-Objekt beantworten die Frage oft, ohne Datensätze zurückzugeben. Die günstigste Antwort ist die, die keine Daten enthält.

Regel drei: In der Tool-Ebene trimmen, wenn die API nicht Ihnen gehört

Drittanbieter-APIs werden keine Feldauswahl hinzufügen, nur weil Sie darum gebeten haben. Führen Sie das Trimmen stattdessen in Ihrem Executor durch, zwischen der HTTP-Antwort und dem Modell.

KEEP = {
    "getCustomer": ["id", "email", "plan", "status"],
    "listOrders": ["id", "total", "status", "created_at"],
}

def project(tool_name, payload):
    keep = KEEP.get(tool_name)
    if keep is None:
        return payload
    if isinstance(payload, list):
        return [{k: item.get(k) for k in keep if k in item} for item in payload]
    return {k: payload.get(k) for k in keep if k in payload}

Drei Verfeinerungen machen dies in der Praxis haltbar.

Speichern Sie die vollständige Antwort und geben Sie dem Modell die Projektion. Behalten Sie die ungetrimmte Nutzlast in Ihrem Ausführungsprotokoll, damit das Debugging weiterhin möglich ist. Unser Beitrag zum Tracing von Agenten-Tool-Aufrufen behandelt, was aufgezeichnet werden soll.

Teilen Sie dem Modell mit, was Sie entfernt haben. Eine Zeile wie "_omitted": ["billing_address", "notes", "metadata"] ermöglicht es ihm, den vollständigen Datensatz anzufordern, wenn es ihn wirklich benötigt, anstatt zu schlussfolgern, dass die Daten nicht existieren.

Wandeln Sie Listen in ein kompaktes Format um. Bei tabellarischen Ergebnissen kosten CSV oder eine Markdown-Tabelle weitaus weniger Tokens als JSON, da Feldnamen nur einmal anstelle pro Zeile erscheinen. Modelle können beides gut lesen.

id,total,status,created_at
ord_91,4900,paid,2026-08-21
ord_92,1200,refunded,2026-08-22

Regel vier: Für schwere Fälle auf dem Server zusammenfassen

Manche Fragen benötigen überhaupt keine Datensätze. „Hatte dieser Kunde diesen Monat Zahlungsausfälle?“ ist eine boolesche Frage. 40 Zahlungs-Objekte zurückzugeben, damit das Modell dies selbst herausfinden kann, ist der teure Weg, zu antworten.

Wo eine Frage wiederkehrt, fügen Sie den Endpunkt hinzu, der sie direkt beantwortet. Eine Zusammenfassung des Kontostatus, ein Status-Rollup, eine kleine Aggregation. Das sieht aus wie gewöhnliche API-Designarbeit, weil es das auch ist, und es ist die wertvollste Version von allem oben Genannten: Anstatt eine große Antwort zu kürzen, vermeiden Sie es, überhaupt eine zu erzeugen.

Zwei Schutzmaßnahmen. Halten Sie Zusammenfassungen in ihrer Form stabil, damit Agenten sich auf sie verlassen können, und versionieren Sie sie, da ein Prompt eines Agenten gegen eine bestimmte Form geschrieben wird und eine stille Änderung dies zerstört. Unser Beitrag über was passiert, wenn sich die API unter einem Agenten ändert behandelt dieses Risiko, und die beste API-Versionierungsstrategie behandelt die Mechanik.

Vorher und nachher messen

Nichts davon sollte blind durchgeführt werden. Drei Zahlen verraten Ihnen, wo das Problem liegt.

Bytes pro Antwort, pro Endpunkt. Senden Sie eine realistische Anfrage an jedes Tool, das Ihr Agent aufrufen kann, und protokollieren Sie die Nutzlastgröße. Alles über wenige Kilobytes ist ein Kandidat. In Apidog können Sie jeden Endpunkt einmal ausführen und die Größe direkt aus der Antwort ablesen, dann die Anfrage speichern, damit die Prüfung bei API-Änderungen wiederholt wird.

Tokens pro Tool-Aufruf. Bytes sind ein Proxy; Tokens sind die Rechnung. Führen Sie die Nutzlasten durch den Tokenizer Ihres Anbieters, wie z.B. tiktoken für OpenAI-Modelle, und rangieren Sie die Endpunkte. Die Rangliste ist normalerweise unausgewogen, wobei ein oder zwei Endpunkte für die meisten Kosten verantwortlich sind.

Kontextverbrauch pro Durchlauf. Protokollieren Sie die laufende Gesamtsumme über eine ganze Agentenaufgabe. Wenn eine Aufgabe nahe der Grenze endet, verschafft Ihnen das Trimmen abgeschlossene Durchläufe, nicht nur günstigere.

Entwerfen Sie dann die gewünschte Form und modellieren Sie sie, bevor das API-Team sie implementiert. Ein Mock-Server, der die gekürzte Antwort zurückgibt, ermöglicht es Ihnen, die Verbesserung zu messen und zu überprüfen, ob der Agent mit weniger Daten immer noch erfolgreich ist, was die eigentlich wichtige Frage ist. Unser Beitrag über das Ausführen von Agenten gegen Mocks statt in der Produktion behandelt den Workflow.

Wie gut aussieht

Eine agentenfreundliche Antwort ist klein, flach und ehrlich darüber, was sie ausgelassen hat:

{
  "customer": { "id": "8812", "email": "dana@example.com", "plan": "pro" },
  "recent_orders": [
    { "id": "ord_91", "total_cents": 4900, "status": "paid" },
    { "id": "ord_92", "total_cents": 1200, "status": "refunded" }
  ],
  "recent_orders_total": 47,
  "truncated": true,
  "_omitted": ["billing_address", "metadata", "order_line_items"]
}

Unter 200 Tokens. Es beantwortet die häufig gestellte Frage, es besagt, dass es 47 Bestellungen gibt, anstatt zwei zu implizieren, und es teilt dem Modell mit, wonach es als Nächstes fragen kann.

Beginnen Sie mit Ihrem lautesten Endpunkt. Messen Sie ihn, fügen Sie Feldauswahl hinzu, begrenzen Sie die Liste und führen Sie den Agenten erneut aus. Die Lücke zwischen den beiden Zahlen ist normalerweise groß genug, um den Rest der Arbeit zu rechtfertigen. Laden Sie Apidog herunter, wenn Sie die Messung und den Mock im selben Projekt wünschen.

Drei Bereiche, in denen dies auftritt

• Support-Triage. Ein Agent liest ein Ticket, ruft den Kunden ab und entscheidet, ob eine Eskalation notwendig ist. Die naive Version holt das vollständige Kundenobjekt und die letzten 50 Tickets ab und verbrennt 30.000 Tokens, bevor sie die eigentliche Beschwerde liest. Die korrigierte Version ruft einen Übersichts-Endpunkt auf, der Plan, Status, Anzahl offener Tickets und letztes Kontaktdatum zurückgibt. Rund 80 Tokens, und die Eskalationsentscheidung wird besser, weil die relevanten Fakten nicht vergraben sind.
• Interne Betriebs-Agenten. Ein Deployment-Agent überprüft die Dienstintegrität über 40 Dienste hinweg. Volle Statusobjekte sprengen das Fenster bei Dienst 12. Ein Rollup, der eine Zeile pro Dienst zurückgibt – Name plus Status plus Fehlerrate – passt alle 40 in ein paar hundert Tokens und ermöglicht es dem Agenten, über die gesamte Flotte zu folgern, anstatt die erste Hälfte zu vergessen.
• Dateneingabe und Abgleich. Ein Agent gleicht Rechnungen mit Zahlungen ab. Das Zurückgeben vollständiger Rechnungsdokumente führt dazu, dass er nach einigen Dutzend Datensätzen versagt. Das Zurückgeben von id, amount_cents, date und reference als CSV ermöglicht es ihm, mehrere hundert in einem Durchlauf zu verarbeiten, da der Vergleich immer nur vier Felder verwendete.

Das Muster bei allen dreien: Der Agent benötigte eine Entscheidungsgrundlage, und die API lieferte ein Dokument.

Sie benötigen eine Ausführungshistorie, um das Muster zu erkennen

Ein einziger Durchlauf zeigt Ihnen, dass eine Antwort groß war. Das Muster, welcher Endpunkt das Budget sprengt und wie oft, zeigt sich nur über mehrere Durchläufe hinweg.

Das bedeutet, dass die Zahlen die Sitzung überleben müssen. Für einen von Ihnen bereitgestellten Dienst ist das Ihre eigene Telemetrie. Für Programmieragenten, die zugewiesene Arbeiten ausführen, ist es die Plattform, auf der sie laufen: Sharkly speichert den Ausführungsverlauf und das Ergebnis jedes Durchlaufs bei der jeweiligen Aufgabe, sodass der Vergleich von Durchlauf zu Durchlauf eine Frage des Lesens der Aufgabenhistorie ist, anstatt Terminal-Sitzungen zu rekonstruieren. So oder so, Budgeteinhaltung ohne Historie sagt Ihnen, dass etwas zu groß ist, aber nicht, was zuerst behoben werden muss.

Legen Sie ein Budget pro Tool fest, nicht nur pro Durchlauf

Die meisten Teams begrenzen den Gesamtk Kontext und hören dort auf. Ein Pro-Tool-Budget ist nützlicher, weil es ein vages Problem in ein spezifisches umwandelt.

Geben Sie jedem Tool eine Obergrenze, zum Beispiel 1.500 Tokens. Wenn eine Antwort diese überschreitet, kürzt der Executor auf die Projektion, fügt den Marker für ausgelassene Felder hinzu und protokolliert den Überlauf. Jetzt haben Sie eine Liste von Endpunkten, die regelmäßig das Budget überschreiten, geordnet danach, wie oft der Agent sie aufruft – das ist Ihre Arbeitswarteschlange.

Das Budget schützt Sie auch vor Endpunkten, die im Test klein sind und für einen echten Kunden riesig ausfallen. Verteilungen haben Ränder, und das Konto mit 4.000 Bestellungen ist dasjenige, das einen Durchlauf um 2 Uhr morgens zum Absturz bringen wird. Eine feste Obergrenze verwandelt dies in eine gekürzte Antwort anstelle einer fehlgeschlagenen Aufgabe.

Häufig gestellte Fragen

• Ist das Kürzen von Antworten riskant, wenn der Agent die fehlenden Daten benötigt? Nur wenn Sie die Kürzung verbergen. Fügen Sie einen expliziten Marker und eine Liste der ausgelassenen Felder hinzu, damit das Modell diese anfordern kann. Stilles Kürzen führt zu falschen Antworten, nicht das Trimmen an sich.
• Sollte ich stattdessen GraphQL für Agenten verwenden? GraphQL macht die Feldauswahl obligatorisch, was dies sauber löst, aber es verlagert die Komplexität in die Abfrageerstellung, und Modelle schreiben häufiger ungültige Abfragen, als dass sie eine Feldliste falsch verwenden. Das Hinzufügen von fields zu REST-Endpunkten ist in der Regel die kleinere Änderung.
• Wie klein sollte eine Tool-Antwort sein? Zielen Sie auf unter 1.000 Tokens für eine Einzeldatensatzlesung und unter 2.000 für eine Liste ab. Darüber hinaus fragen Sie sich, ob der Agent Datensätze oder eine Antwort benötigt.
• Löst Prompt-Caching dieses Problem? Es reduziert die Kosten des wiederholten Kontextes, nicht den von ihm belegten Platz. Eine gecachte 40.000-Token-Antwort füllt das Fenster immer noch aus, sodass Caching zwar die Rechnung senkt, das Zuverlässigkeitsproblem aber intakt bleibt.
• Was ist mit Binär- und Datei-Antworten? Platzieren Sie diese niemals im Kontext. Speichern Sie die Datei, übergeben Sie dem Agenten eine Referenz und eine kurze Beschreibung und geben Sie ihm ein separates Tool, um nur das zu extrahieren, was er benötigt.
• Wo sollte das Trimmen erfolgen, in der API oder im Tool-Wrapper? In der API, wenn Sie sie besitzen, da jeder Aufrufer davon profitiert und die Bytes niemals das Netzwerk überqueren. Im Wrapper, wenn Sie sie nicht besitzen. Beides ist in Ordnung.