KI-Agent Kontextfenster: Überladene API-Antworten optimieren

API-Antworten für KI-Agenten optimieren: weniger Tokens, mehr Zuverlässigkeit

Der Agent fragt nach einem Kundendatensatz. Ihre API liefert den Kunden, die letzten 200 Bestellungen, jeden einzelnen Bestellposten, Zeitstempel in drei Formaten und zusätzlich einen _links-Block pro Objekt. So landen 40.000 Token im Kontextfenster, obwohl der Agent nur die E-Mail-Adresse benötigt.

Apidog heute ausprobieren

Wiederholen Sie das viermal in einem Durchlauf, verbringt der Agent den größten Teil seines Budgets damit, JSON zu lesen, das er nie angefordert hat. Danach treten die typischen Fehler auf: Die ursprüngliche Anweisung wird vergessen, die Aufgabe wird zusammengefasst statt abgeschlossen und die Kosten pro Durchlauf steigen, während die Qualität sinkt.

Das ist ein API-Designproblem, kein Prompt-Problem. Agenten arbeiten innerhalb eines festen Kontextfensters. Jedes zurückgegebene Feld konkurriert mit Anweisungen, Konversation und Plan. Dieser Leitfaden zeigt:

• woher die Überladung kommt,
• wie Feldauswahl und Paginierung sie reduzieren,
• wie Sie Antworten im Tool-Wrapper trimmen,
• wann serverseitige Zusammenfassungen sinnvoll sind,
• und wie Sie die Verbesserung messen.

Unser Artikel darüber, warum KI-Agenten in der Produktion versagen, behandelt Kontextüberlastung als eine der zentralen Fehlerursachen. Hier geht es um die praktische Umsetzung.

Mit Apidog können Sie die tatsächliche Antwortgröße jedes Endpunkts messen, bevor ein Agent ihn aufruft. Außerdem lässt sich die gewünschte gekürzte Antwortform modellieren, bevor das API-Team sie implementiert.

Wohin die Tokens gehen

Antworten für Browser und Dashboards enthalten oft viele Daten, die für Agenten teuer sind.

• Ausführliche Umschläge: Ein data-, meta-, links- oder included-Wrapper um ein Objekt mit fünf Feldern kann die Nutzlast verdoppeln. Hypermedia-Links sind nützlich für Clients, die ihnen folgen. Agenten tun das selten, und jede URL kostet Tokens.
• Wiederholte Schlüssel: JSON wiederholt jeden Feldnamen in jedem Array-Element. Eine Liste mit 200 Elementen und 15 Feldern bezahlt also 3.000 Schlüssel-Strings.
• Verschachtelte Erweiterungen: Ein Kunde mit Bestellungen und Bestellposten bildet einen Baum. Solche Strukturen wachsen schnell, wenn sie standardmäßig inline geliefert werden.
• Redundante Formate: created_at, created_at_unix und created_at_human sind drei Darstellungen desselben Werts.
• Nullwerte und leere Felder: Serializer geben häufig jedes Feld aus, auch wenn es nicht gesetzt ist. Zwanzig null-Werte pro Datensatz sind reine Verschwendung.

Tokenkosten hängen von der Größe des serialisierten Textes ab, nicht allein von der Anzahl der Datensätze. Zweihundert Datensätze mit jeweils fünf Feldern können günstiger sein als ein einzelnes tief verschachteltes Objekt.

Regel 1: Felder zurückgeben, nicht ganze Ressourcen

Die wertvollste Änderung ist eine Feldauswahl, mit der der Aufrufer genau die benötigten Daten anfordert:

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

{
  "id": "8812",
  "email": "[e-mail]",
  "plan": "pro",
  "status": "active"
}

Bei vielen APIs reduziert das die Antwortgröße gegenüber einem vollständigen Datensatz um etwa 90 Prozent und lässt sich an einem Nachmittag implementieren. Googles API-Designhandbuch dokumentiert das Field-Mask-Muster. GraphQL löst dasselbe Problem, indem die Auswahl verpflichtend ist.

Beachten Sie zwei Punkte:

1. Validieren Sie die Feldliste gegen das Schema und lehnen Sie unbekannte Namen ab. Ein halluziniertes Feld sollte einen klaren Fehler erzeugen, nicht stillschweigend ein gekürztes Objekt.
2. Definieren Sie einen kleinen Standardsatz für Aufrufer ohne fields. Geben Sie nicht standardmäßig alles zurück.

Machen Sie die Feldauswahl auch in der Tool-Beschreibung für das Modell sichtbar:

{
  "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."
      }
    }
  }
}

Die Beschreibung ist der Ort, an dem das Modell diese Regeln lernt. Sowohl der OpenAI-Leitfaden für Funktionsaufrufe als auch die Anthropic-Dokumentation zur Tool-Nutzung betonen die Bedeutung präziser Tool-Beschreibungen.

Der entscheidende Schritt ist fields als Pflichtfeld. Optionale Parameter werden übersprungen. Ein Pflichtfeld zwingt das Modell, zu überlegen, welche Daten es tatsächlich benötigt.

Regel 2: Listen immer begrenzen

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

Legen Sie ein festes serverseitiges Maximum fest. Wenn der Agent limit=5000 sendet, liefern Sie höchstens 100 Einträge und teilen Sie die Begrenzung mit.

Die REST-API-Paginierung und das Design von Paginierung für Millionen von Datensätzen behandeln die allgemeine Mechanik. Für Agenten gelten besonders diese Regeln:

• Begrenzen Sie eine Seite auf etwa 20 bis 50 Einträge.
• Geben Sie eine Gesamtzahl zurück, damit der Agent weiß, ob er alles gesehen hat.
• Verwenden Sie Cursor-Paginierung. Offsets verschieben sich, wenn sich Daten während des Durchlaufs ändern.
• Fügen Sie einen eindeutigen Marker wie "truncated": true hinzu. Modelle schließen aus der Array-Länge häufig fälschlich auf Vollständigkeit.

Geben Sie dem Agenten außerdem Alternativen zur vollständigen Paginierung:

• einen count-Endpunkt,
• eine gefilterte Suche mit engem Zeitfenster,
• oder ein Übersichtsobjekt.

Die günstigste Antwort ist oft die, die überhaupt keine Datensätze enthält.

Regel 3: Im Tool-Wrapper trimmen, wenn Sie die API nicht kontrollieren

Drittanbieter-APIs werden nicht automatisch Feldauswahl unterstützen. In diesem Fall trimmen Sie die Antwort im Executor zwischen HTTP-Client und 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 Ergänzungen machen dieses Muster praxistauglich:

Vollständige Antworten protokollieren

Speichern Sie die vollständige HTTP-Antwort, geben Sie dem Modell aber nur die Projektion. So bleibt das Debugging möglich. Der Beitrag zum Tracing von Agenten-Tool-Aufrufen beschreibt, welche Daten Sie dabei aufzeichnen sollten.

Ausgelassene Felder sichtbar machen

Teilen Sie dem Modell mit, was entfernt wurde:

{
  "id": "8812",
  "email": "[e-mail]",
  "_omitted": ["billing_address", "notes", "metadata"]
}

Damit kann der Agent die vollständigen Daten gezielt anfordern, statt anzunehmen, dass sie nicht existieren. Stilles Kürzen führt zu falschen Antworten.

Listen in kompakte Formate umwandeln

Bei tabellarischen Ergebnissen sind CSV oder Markdown-Tabellen oft günstiger als JSON, weil die Feldnamen nicht in jeder Zeile wiederholt werden. Modelle können beide Formate gut lesen:

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

Regel 4: Schwere Fragen serverseitig zusammenfassen

Viele Fragen benötigen keine einzelnen Datensätze. Die Frage „Hatte dieser Kunde diesen Monat Zahlungsausfälle?“ ist eine boolesche Abfrage. Vierzig Zahlungsobjekte zurückzugeben und den Agenten selbst rechnen zu lassen, ist der teure Weg.

Wenn eine Frage regelmäßig vorkommt, ergänzen Sie einen Endpunkt, der sie direkt beantwortet:

• Kontostatus-Zusammenfassung,
• Status-Rollup,
• kleine Aggregation,
• oder ein speziell zugeschnittenes Übersichtsobjekt.

Das ist gewöhnliche API-Designarbeit und zugleich die wirksamste Optimierung: Sie kürzen keine große Antwort, sondern erzeugen sie gar nicht erst.

Halten Sie Zusammenfassungen stabil und versionieren Sie sie. Agenten-Prompts sind gegen eine bestimmte Antwortform geschrieben; eine stille Schemaänderung kann sie brechen. Lesen Sie dazu auch, was passiert, wenn sich die API unter einem Agenten ändert, sowie die Empfehlungen zur besten API-Versionierungsstrategie.

Vorher und nachher messen

Führen Sie diese Änderungen nicht blind durch. Drei Kennzahlen zeigen, wo das Problem liegt.

1. Bytes pro Antwort und Endpunkt

Senden Sie eine realistische Anfrage an jedes Tool, das Ihr Agent aufrufen kann, und protokollieren Sie die Nutzlastgröße. Antworten über wenige Kilobytes sind Kandidaten für Feldauswahl oder Projektion.

In Apidog können Sie jeden Endpunkt ausführen, die Antwortgröße direkt ablesen und die Anfrage speichern. So lässt sich die Prüfung bei späteren API-Änderungen wiederholen.

2. Tokens pro Tool-Aufruf

Bytes sind nur ein Proxy. Tokens sind die tatsächliche Rechnung. Verarbeiten Sie die Nutzlasten mit dem Tokenizer Ihres Anbieters, beispielsweise mit tiktoken für OpenAI-Modelle, und sortieren Sie die Endpunkte nach Kosten.

Die Verteilung ist normalerweise unausgewogen: Ein oder zwei Endpunkte verursachen den größten Teil des Verbrauchs.

3. Kontextverbrauch pro Durchlauf

Protokollieren Sie die laufende Gesamtsumme über eine vollständige Agentenaufgabe. Wenn eine Aufgabe regelmäßig nahe an der Kontextgrenze endet, ermöglicht Trimming abgeschlossene Durchläufe statt nur geringerer Kosten.

Modellieren Sie die gewünschte Antwortform anschließend, bevor das API-Team sie implementiert. Ein Mock-Server mit der gekürzten Antwort zeigt, ob der Agent mit weniger Daten weiterhin erfolgreich ist. Genau das ist die wichtigste Messgröße. Der Workflow zum [Ausführen von Agenten gegen Mocks statt in der Produktion](https://apidog.com/de/blog/ai-agents-mock-apis-not-productionjson
{
"customer": {
"id": "8812",
"email": "[e-mail]",
"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"]
}

Diese Antwort bleibt unter 200 Tokens. Sie beantwortet die häufige Frage, nennt 47 Bestellungen statt fälschlich zwei zu suggerieren und zeigt dem Modell, welche Daten es als Nächstes anfordern kann.

Beginnen Sie mit dem lautesten Endpunkt:

1. Antwortgröße messen.
2. Feldauswahl hinzufügen.
3. Listen begrenzen.
4. Agent erneut ausführen.
5. Erfolgsrate und Kontextverbrauch vergleichen.

Die Differenz ist meist groß genug, um die weitere Arbeit zu rechtfertigen. Wenn Sie Messung und Mocking im selben Projekt benötigen, können Sie [Apidog herunterladen](https://apidog.com/download?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation).

## Drei typische Einsatzbereiche

- **Support-Triage:** Ein Agent liest ein Ticket, ruft den Kunden ab und entscheidet über eine Eskalation. Die naive Variante lädt das vollständige Kundenobjekt und die letzten 50 Tickets und verbraucht 30.000 Tokens, bevor sie die eigentliche Beschwerde liest. Ein Übersichts-Endpunkt mit Plan, Status, Anzahl offener Tickets und letztem Kontaktdatum benötigt etwa 80 Tokens und verbessert die Entscheidung, weil relevante Fakten nicht verborgen bleiben.
- **Interne Betriebs-Agenten:** Ein Deployment-Agent prüft 40 Dienste. Vollständige Statusobjekte sprengen das Kontextfenster bei Dienst 12. Ein Rollup mit einer Zeile pro Dienst — Name, Status und Fehlerrate — passt mit wenigen hundert Tokens vollständig in den Kontext.
- **Dateneingabe und Abgleich:** Ein Agent gleicht Rechnungen mit Zahlungen ab. Vollständige Rechnungsdokumente führen nach einigen Dutzend Datensätzen zum Scheitern. `id`, `amount_cents`, `date` und `reference` als CSV ermöglichen den Vergleich mehrerer hundert Datensätze.

Das gemeinsame Muster: Der Agent benötigt eine Entscheidungsgrundlage, die API liefert aber ein vollständiges Dokument.

## Sie benötigen eine Ausführungshistorie

Ein einzelner Durchlauf zeigt nur, dass eine Antwort groß war. Erst mehrere Durchläufe zeigen, welcher Endpunkt das Budget regelmäßig sprengt und wie oft er aufgerufen wird.

Diese Zahlen müssen die Sitzung überleben:

- Bei einem selbst betriebenen Dienst übernimmt das Ihre Telemetrie.
- Bei Programmieragenten speichert die Plattform die Ausführungshistorie und das Ergebnis jedes Durchlaufs an der jeweiligen Aufgabe.

[Sharkly](https://sharkly.ai) speichert beispielsweise den Verlauf und das Ergebnis jedes Laufs. So können Sie Durchlauf zu Durchlauf vergleichen, ohne Terminal-Sitzungen zu rekonstruieren.

Ohne Historie wissen Sie nur, dass etwas zu groß ist — nicht, was Sie zuerst beheben sollten.

![Ausführungshistorie hilft beim Erkennen wiederkehrender Kontextprobleme](https://assets.apidog.com/blog-next/2026/08/image-118.png)

## Ein Budget pro Tool statt nur pro Durchlauf

Viele Teams begrenzen den Gesamtkontext und belassen es dabei. Ein Budget pro Tool macht das Problem konkreter.

Geben Sie jedem Tool eine Obergrenze, beispielsweise 1.500 Tokens. Überschreitet eine Antwort diesen Wert, soll der Executor:

1. auf eine definierte Projektion kürzen,
2. einen `_omitted`-Marker hinzufügen,
3. und den Überlauf protokollieren.

Damit entsteht eine priorisierte Arbeitsliste: Endpunkte, die regelmäßig das Budget überschreiten, sortiert nach Überlaufhäufigkeit und Aufrufzahl.

Das Budget schützt außerdem vor Ausreißern. Ein Endpunkt kann im Test klein sein und für einen echten Kunden riesig werden. Das Konto mit 4.000 Bestellungen ist genau der Fall, der einen nächtlichen Lauf zum Absturz bringt. Eine harte Obergrenze macht daraus eine kontrollierte, gekürzte Antwort statt einer fehlgeschlagenen Aufgabe.

## Häufig gestellte Fragen

### Ist das Kürzen von Antworten riskant?

Nur, wenn Sie die Kürzung verbergen. Fügen Sie einen expliziten Marker und eine Liste ausgelassener Felder hinzu, damit das Modell die Daten gezielt anfordern kann. Stilles Kürzen führt zu falschen Antworten; Trimming selbst nicht.

### Sollte ich stattdessen GraphQL für Agenten verwenden?

GraphQL macht Feldauswahl verpflichtend und löst das Problem sauber. Dafür verlagert es Komplexität in die Abfrageerstellung. Modelle erzeugen häufiger ungültige GraphQL-Abfragen, als dass sie eine Feldliste falsch verwenden. `fields` in einem REST-Endpunkt ist meist die kleinere Änderung.

### Wie klein sollte eine Tool-Antwort sein?

Zielen Sie auf:

- unter 1.000 Tokens für das Lesen eines einzelnen Datensatzes,
- unter 2.000 Tokens für eine Liste.

Wenn die Antwort größer wird, prüfen Sie, ob der Agent tatsächlich Datensätze oder nur eine Entscheidungshilfe benötigt.

### Löst Prompt-Caching das Problem?

Prompt-Caching reduziert die Kosten wiederholten Kontexts, nicht den belegten Platz. Eine gecachte Antwort mit 40.000 Tokens füllt das Kontextfenster weiterhin. Caching senkt also die Rechnung, beseitigt aber nicht das Zuverlässigkeitsproblem.

### Was ist mit Binär- und Dateiantworten?

Platzieren Sie Binärdaten niemals direkt im Kontext. Speichern Sie die Datei, übergeben Sie dem Agenten eine Referenz und eine kurze Beschreibung und stellen Sie ein separates Tool bereit, das nur die benötigten Informationen extrahiert.

### Wo sollte das Trimming erfolgen?

Wenn Sie die API besitzen, trimmen Sie dort. Dann profitieren alle Aufrufer und die überflüssigen Bytes verlassen den Server gar nicht erst. Bei einer fremden API trimmen Sie im Tool-Wrapper. Beide Varianten sind sinnvoll.