Typisierte Tools halten Agenten von API-Blindstellen fern

Ein Agent soll entscheiden, was zu tun ist. Er darf nie erfinden, wie Ihre API es ausgeführt haben will. Diese Trennung klingt selbstverständlich, bis ein Modell customer_id sendet, obwohl der Endpunkt accountId erwartet, aus einer Vorschau eine Aktualisierung macht oder ein unbekanntes Enum mit einem plausiblen Wort füllt. Die Anfrage kann im Gesprächsprotokoll gut aussehen und trotzdem ungültig, mehrdeutig oder gefährlich sein.

Typisierte Tools verlagern diese Mehrdeutigkeit aus dem Prompt in einen durchsetzbaren Vertrag. Das Modell erhält eine begrenzte Menge von Operationen, jeweils mit einer maschinell prüfbaren Eingabeform. Ihre Anwendung validiert den Aufruf, bevor er die Geschäftslogik erreicht, und verlangt dann für jede zustandsändernde Operation eine menschliche Freigabe. Das Modell denkt weiterhin über die Absicht nach. Der Code kontrolliert Syntax, Berechtigung und Ausführung.

Ich habe erlebt, wie Teams einen ausführlichen System-Prompt wie eine Schnittstellendefinition behandelten. Das ist er nicht. Prosa kann Richtlinien erklären, aber sie kann kein zusätzliches Feld ablehnen, keine diskriminierte Union durchsetzen, keine Versionsnummer vergleichen und keine doppelte Abbuchung durch einen Wiederholungsversuch verhindern. Wenn ein Agent eine Produktions-API erreichen kann, gehören diese Kontrollen in den Code.

Ein Prompt beschreibt die Absicht, ein Tool-Vertrag die Erlaubnis

Ein Prompt kann einem Agenten sagen, dass er einen Kunden erst nach Bestätigung aktualisieren darf. Ein Tool-Vertrag legt genau fest, welche Aktualisierung existiert, welche Felder sie annimmt und was Bestätigung bedeutet. Im Gespräch überschneiden sich diese Aufgaben, doch sie haben verschiedene Fehlerarten. Prosa scheitert an der Auslegung. Verträge scheitern sichtbar durch Validierung, und genau diese Fehler lassen sich testen und betreiben.

Nehmen wir an, eine interne API stellt einen breiten Endpunkt namens execute_action bereit. Seine Argumente action, resource und payload sind allesamt Zeichenketten. Der Prompt zählt erlaubte Aktionen auf und enthält Beispiele. Dieses Design wirkt flexibel, weil eine neue Aktion keine Schemaänderung braucht. Gleichzeitig bildet es einen Tunnel um jede Einschränkung, die Ihre API bereits durchzusetzen gelernt hat. Das Modell kann eine Aktion falsch schreiben, serialisiertes JSON in payload senden oder eine Ressource mit einer Aktion kombinieren, die nie dafür vorgesehen war.

Eine typisierte Oberfläche sollte schmale Operationen wie get_customer, preview_address_change und commit_address_change bereitstellen. Jeder Name trägt genau eine Fähigkeit. Jedes Eingabeschema begrenzt das Modell auf die Felder, die diese Operation verwenden darf. Braucht das Modell eine nicht unterstützte Aktion, muss der Aufruf als nicht unterstützt scheitern. Ein abgelehnter Aufruf ist sicherer als ein erratener und zeigt, wo der Tool-Katalog ergänzt werden muss.

An dieser Stelle verwechseln Teams Typsicherheit auch mit Prompt-Formatierung. Das Modell um eine JSON-Antwort zu bitten, erleichtert das Parsen. Dadurch wird das JSON noch nicht für Ihr Geschäft gültig. Syntax sagt, dass die Klammern zusammenpassen. Ein Tool-Vertrag sagt, dass country einen erlaubten Code nutzt, customer_id die richtige Art von Datensatz bezeichnet und ein Schreibvorgang einen freigegebenen Vorschlag braucht. Sie benötigen beide Ebenen.

Behalten Sie Beschreibungen, aber geben Sie ihnen eine kleinere Aufgabe. Eine Beschreibung erklärt, wann ein Tool verwendet wird und was seine Begriffe bedeuten. Das Schema entscheidet, was die Grenze überqueren darf. Wenn eine Einschränkung nach der Textgenerierung des Modells noch zählt, codieren Sie sie dort, wo der Ausführer sie prüfen kann.

Gute Schemas erschweren ungültige Zustände

Ein brauchbares Schema bezeichnet Felder nicht nur als Zeichenketten. Es bildet die Entscheidungen ab, die das Verhalten verändern, und weist sinnlose Kombinationen zurück. Wenn eine API entweder eine vorhandene Lieferadresse oder eine neue Adresse annimmt, modellieren Sie das als zwei getrennte Fälle. Akzeptieren Sie nicht zwölf optionale Felder in der Hoffnung, der Prompt erkläre, welche sechs zusammengehören.

Dieses JSON-Schema-Fragment gibt dem Modell eine eindeutige Wahl und sperrt das Objekt gegen erfundene Felder:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["customer_id", "destination"],
  "properties": {
    "customer_id": {"type": "string", "minLength": 1},
    "destination": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "address_id"],
          "properties": {
            "kind": {"const": "saved"},
            "address_id": {"type": "string"}
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "line1", "city", "country"],
          "properties": {
            "kind": {"const": "new"},
            "line1": {"type": "string"},
            "city": {"type": "string"},
            "country": {"type": "string", "pattern": "^[A-Z]{2}$"}
          }
        }
      ]
    }
  }
}

Das Feld kind ist ein Diskriminator. Es verhindert, dass eine Kennung für eine gespeicherte Adresse in den Fall für eine neue Adresse rutscht, und gibt Validierungsfehlern einen brauchbaren Ort. additionalProperties: false ist wichtig, weil Modelle häufig hilfreich aussehende Extras erzeugen. Wer diese Felder still ignoriert, gewöhnt alle Beteiligten an eine Abweichung zwischen Gesprächsprotokoll und tatsächlich ausgeführter Aktion. Weisen Sie sie zurück.

Codieren Sie Tatsachen, die Live-Daten benötigen, nicht als statische Enums. Eine Liste von Lager-, Benutzer- oder aktuellen Tarifkennungen veraltet. Nehmen Sie stabiles Vokabular wie draft, approved und cancelled ins Schema auf. Ermitteln Sie veränderliche Kennungen über ein Lese-Tool und prüfen Sie sie bei der Ausführung gegen das führende System.

Datumswerte, Geld und Mengen brauchen eindeutige Darstellungen. Verwenden Sie eine ISO-Datumszeichenkette, wenn die API ein Kalenderdatum meint, und keinen Zeitstempel mit impliziter Zeitzone. Stellen Sie Geld als Ganzzahl in der kleinsten unterstützten Einheit plus Währungscode dar, sofern das vorhandene Domänenmodell keine andere exakte Form vorgibt. Ergänzen Sie Mindest- und Höchstwerte, Zeichenlängen und Muster, wo die Domäne sie kennt. Jede fehlende Grenze wird zu einem Wert, den der Agent vernünftigerweise ausprobieren kann.

Schemaversionierung sollte langweilig sein. Geben Sie jedem Tool im Register eine Version, halten Sie alte Versionen verfügbar, solange aktive Läufe sie noch aufrufen können, und führen Sie inkompatible Änderungen unter einer neuen Version ein. Wenn ein bisher optionales Feld ohne Versionswechsel verpflichtend wird, kann aus einem normalen Wiederholungsversuch des Agenten ein rätselhafter Validierungsfehler werden.

Vor und nach der Geschäftslogik validieren

Die Validierung an der Grenze braucht zwei Durchläufe. Prüfen Sie zuerst die Argumente des Modells gegen das veröffentlichte Tool-Schema. Prüfen Sie anschließend Domänenfakten in dem Dienst, dem diese Fakten gehören. Der erste Durchlauf fängt fehlerhafte Aufrufe ab. Der zweite erkennt formal richtige Aufrufe, deren Annahmen nicht mehr stimmen.

Eine Anfrage mit customer_id: "C-1842" kann jede JSON-Regel erfüllen und trotzdem auf einen gelöschten Datensatz oder einen Kunden außerhalb des Mandanten des Bedieners zeigen. Eine positive quantity kann den verfügbaren Bestand überschreiten. Ein approved Vorschlag kann abgelaufen sein. Der Tool-Adapter darf einen Schemaerfolg weder als Berechtigung noch als gültigen Domänenzustand behandeln.

Geben Sie Fehler als typisierte Ergebnisse zurück, nicht als Absätze, die das Modell neu deuten muss. Ein stabiler Fehlerumschlag liefert dem Planer genug Information zur Erholung, ohne Stacktraces offenzulegen:

{
  "ok": false,
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Customer changed after the proposal was created",
    "retryable": false,
    "field": "expected_version"
  }
}

Der Code dient dem Kontrollfluss. Die Nachricht ist für das Protokoll und den Bediener. Das Wiederholungskennzeichen teilt der Laufzeit mit, ob ein identischer Aufruf jemals helfen könnte. Halten Sie diese Bedeutungen über alle Tools hinweg stabil. Wenn jeder Adapter eigene Fehlerprosa erfindet, wird das Modell ungewollt zu Ihrem Fehlerparser.

Validieren Sie auch Ausgaben. Tool-Autoren ändern Code, vorgeschaltete APIs liefern unvollständige Daten und Serialisierer geben Felder preis. Ein Ausgabeschema kann verhindern, dass ein Tool Zugangsdaten, interne Notizen oder ein unerwartetes Megabyte Text in den Modellkontext zurückspeist. Es erkennt außerdem den unangenehmen Fall, dass die Ausführung gelungen ist, sich aber die Ergebnisform geändert hat und der Agent nun aus fehlenden Feldern schließt.

Protokollieren Sie das Validierungsergebnis mit Tool-Name, Schemaversion, Lauf-ID und Fehlercode. Protokollieren Sie rohe Argumente nicht standardmäßig. Tool-Eingaben enthalten oft genau die persönlichen oder betrieblichen Daten, die Sie kontrollieren wollen. Halten Sie Hashes oder ausgewählte unkritische Felder fest, wenn sie als Beleg genügen.

Lese- und Schreibvorgänge gehören in getrennte Fähigkeitssätze

Klassifizieren Sie Tools nach ihrer Wirkung, bevor das Modell sie sieht. Ein Lesevorgang gibt Informationen zurück, ohne dauerhaften Zustand zu verändern. Ein Schreibvorgang erstellt, aktualisiert, löscht, sendet, veröffentlicht, bezahlt, deployt oder stößt ein anderes System an, das eine dieser Handlungen ausführt. Das HTTP-Verb ist kein verlässlicher Klassifikator. Ein GET-Endpunkt kann eine Nachricht als gelesen markieren, ein POST-Endpunkt eine reine Suche ausführen. Klassifizieren Sie die geschäftliche Wirkung.

Geben Sie erkundenden Agenten standardmäßig Lese-Tools. Ergänzen Sie Schreib-Tools nur für den Lauf, der sie braucht, und unter einer Identität mit passenden serverseitigen Berechtigungen. Schreib-Tools im Prompt zu verstecken ist keine Berechtigungskontrolle. Kann die Laufzeit einen benannten Aufruf weiterhin verteilen, können Prompt-Injektion oder Planungsfehler ihn finden. Der Dispatcher muss jedes Tool ablehnen, das nicht zum Fähigkeitssatz des Laufs gehört.

Schreibvorgänge brauchen auch engere Formen. Ein generisches Tool update_record verlangt vom Agenten, jede Tabelle und jede veränderliche Spalte zu verstehen. Stellen Sie Geschäftsoperationen wie suspend_invoice_delivery oder change_shipping_address bereit. Der Dienst kann dann Invarianten durchsetzen, eine brauchbare Vorschau erstellen und genau an diese Wirkung eine Freigaberichtlinie hängen.

Manche Operationen wirken umkehrbar, sind es aber nicht. Eine gesendete E-Mail lässt sich nicht verlässlich zurückrufen. Das Veröffentlichen eines Ereignisses kann mehrere nachgelagerte Aufträge starten. Das Löschen eines neu angelegten Datensatzes macht die bereits versandte Benachrichtigung darüber nicht rückgängig. Behandeln Sie externe Kommunikation und nachgelagerte Auslöser als Schreibvorgänge, selbst wenn Ihre lokale Datenbank unverändert bleibt.

Trennen Sie bei einem gemischten Ablauf Planung und Ausführung. Der Agent kann Datensätze lesen, eine vorgeschlagene Änderung berechnen und sie durch ein Vorschau-Tool bepreisen oder validieren lassen. Das abschließende Commit-Tool nimmt eine Vorschlagskennung an, keine neue freie Nutzlast. Diese eine Designentscheidung verhindert, dass sich die freigegebene Operation zwischen Bildschirm und Schreibvorgang verändert.

Eine Freigabe muss an einen exakten Schreibvorschlag gebunden sein

Eine Freigabeschaltfläche allein bietet wenig Kontrolle. Der Freigabedatensatz muss festhalten, wer was gegen welche Version des Ziels und bis wann genehmigt hat. Sonst kann ein Modell die Freigabe für eine Nutzlast erhalten und eine andere ausführen oder die genehmigte Nutzlast ausführen, nachdem sich der zugrunde liegende Datensatz geändert hat.

Verwenden Sie ein von vertrauenswürdigem Code erzeugtes Vorschlagsobjekt. Der Agent übergibt Kandidatenargumente an ein Vorschau-Tool. Der Dienst validiert sie, löst Standardwerte auf, berechnet Folgen und gibt einen kanonischen Vorschlag zurück. Der Benutzer sieht die kanonische Wirkung, nicht die Gesprächszusammenfassung des Modells. Ein praktischer Freigabedatensatz kann so aussehen:

{
  "proposal_id": "p_7f31",
  "tool": "commit_address_change.v2",
  "arguments_sha256": "8be7...a91c",
  "target": {"type": "customer", "id": "C-1842", "version": 17},
  "effect": "Replace the shipping address for customer C-1842",
  "expires_at": "2026-08-14T16:30:00Z",
  "approved_by": "user_291"
}

Der Commit-Endpunkt lädt diesen Datensatz, prüft die Befugnis des Genehmigenden, kontrolliert den Ablauf, vergleicht die Zielversion und hasht die kanonischen Argumente erneut. Er darf keine Ersatzargumente vom Agenten annehmen. Bei jeder Abweichung stoppt die Ausführung und das System erzeugt einen neuen Vorschlag.

Die Freigaberichtlinie sollte sich nach den Folgen richten, nicht nach der Zahl der Tools. Ein risikoarmer Entwurf in einem isolierten Arbeitsbereich braucht vielleicht keine menschliche Entscheidung. Der Versand dieses Entwurfs an einen Kunden braucht sie. Eine Massenänderung, Zahlung, Löschung, Rotation von Zugangsdaten, Produktionsbereitstellung oder externe Nachricht sollte eine Freigabestufe erhalten, die ihrer Reichweite entspricht. Halten Sie die Regel in einer Richtlinientabelle, die die Laufzeit auswerten kann. Verteilen Sie sie nicht über Prompts.

Der Freigabebildschirm sollte konkrete Unterschiede zeigen: Felder vorher und nachher, Empfänger, Betrag und Währung, Umgebung, Zahl betroffener Datensätze und jede unumkehrbare Folge. Bitten Sie niemanden, run tool call zu genehmigen. Freigabemüdigkeit entsteht, wenn der Bildschirm die Wirkung verbirgt und den Bediener zwingt, der Zusammenfassung des Agenten zu vertrauen.

Freigaben sollten ablaufen, und die meisten sollten nur einmal gelten. Erfassen Sie auch Ablehnungen samt kurzer Begründung, die der Agent für eine neue Planung nutzen kann. Machen Sie Schweigen, einen geschlossenen Browser-Tab oder eine Zeitüberschreitung nie zur Zustimmung.

Ein Schreibfehler kann mehrere Minuten wie Erfolg aussehen

Betrachten Sie einen Agenten, der eine Lieferadresse ändert. Er liest Kundenversion 17, schlägt eine neue Adresse vor und erhält die Freigabe. Die Commit-Anfrage erreicht den Dienst, der die Adresse schreibt und die Transaktion bestätigt. Bevor die Antwort den Agenten erreicht, bricht die Verbindung ab. Die Laufzeit sieht eine Zeitüberschreitung. Sie weiß nicht, ob der Schreibvorgang erfolgt ist.

Ein naiver Wiederholungsversuch sendet dieselbe logische Änderung erneut. Wenn der Endpunkt Adressen anhängt oder ein Fulfillment-Ereignis ausgibt, kann die zweite Anfrage Arbeit duplizieren. Meldet die Laufzeit stattdessen einen Fehler, wiederholt der Bediener die Änderung vielleicht manuell. Das Protokoll sagt, das Tool sei gescheitert, obwohl sich die Produktion geändert hat. Dieses mehrdeutige Ergebnis ist ein normales Problem verteilter Systeme, keine Eigenheit des Modells.

Jeder Schreibaufruf braucht einen Idempotenzschlüssel, den nicht das Modell erzeugt. Binden Sie ihn an Lauf, Vorschlag und Operation. Der Dienst speichert den Schlüssel zusammen mit dem Endergebnis möglichst in derselben Transaktionsgrenze wie den Schreibvorgang. Eine Wiederholung mit demselben Schlüssel gibt das gespeicherte Ergebnis zurück. Ein Aufruf, der den Schlüssel mit anderen Argumenten wiederverwendet, muss scheitern.

Die Laufzeit sollte die Zeitüberschreitung in einer festen Folge behandeln:

1. Den Operationsstatus über den Idempotenzschlüssel abfragen.
2. Hat der Dienst Erfolg erfasst, dieses typisierte Ergebnis an den Agenten zurückgeben.
3. Hat der Dienst einen endgültigen Fehler erfasst, den gespeicherten Fehler zurückgeben.
4. Ist der Status unbekannt, pausieren und eskalieren, statt ein Ergebnis zu erfinden.

Optimistische Nebenläufigkeitskontrolle schließt eine weitere Lücke. Der obige Vorschlag zielt auf Version 17. Ändert ein Mensch die Adresse vor dem Commit, lautet die aktuelle Version 18 und der Commit scheitert mit VERSION_CONFLICT. Der Agent muss den neuen Zustand lesen und einen frischen Vorschlag erstellen. Die alte Freigabe erneut zu verwenden würde eine Entscheidung auf Fakten anwenden, die nicht mehr existieren.

Automatische Wiederholungen eignen sich für Lesevorgänge, die sich ausdrücklich als sicher erklären, und für Schreibvorgänge, die durch Idempotenz und ein bekanntes Statusprotokoll geschützt sind. Lassen Sie eine allgemeine Retry-Bibliothek das nicht allein anhand von Netzwerkfehlern entscheiden. Die Tool-Definition sollte ihre Wiederholungsklasse veröffentlichen und der Ausführer sie durchsetzen.

Tool-Ergebnisse brauchen Belege statt Erfolgssätze

Eine erfolgreiche Tool-Antwort braucht genügend strukturierte Belege für die nächste Entscheidung. Done reicht nicht. Geben Sie Ressourcenkennung, neue Version, Operations-ID, geänderte Felder und jeden Folgezustand zurück, von dem der Ablauf abhängt. Halten Sie Anzeigetext von Steuerfeldern getrennt.

Für die Adressänderung könnte ein brauchbares Ergebnis so aussehen:

{
  "ok": true,
  "operation_id": "op_a812",
  "customer_id": "C-1842",
  "previous_version": 17,
  "new_version": 18,
  "changed_fields": ["shipping_address"],
  "committed_at": "2026-08-14T16:22:11Z"
}

Mit dieser Antwort kann der Agent berichten, was geschehen ist, ohne etwas zu erfinden. Ein späterer Schritt kann außerdem new_version in einen weiteren Vorschlag übernehmen. Gibt der Dienst eine menschlich lesbare Nachricht zurück, behandeln Sie sie als Anzeigetext und nie als einzigen Erfolgsbeleg.

Begrenzen Sie die Ergebnisgröße bewusst. Ein Such-Tool sollte eine begrenzte Seite und einen Cursor zurückgeben, nicht jede passende Zeile. Ein Datei-Tool sollte Metadaten und ein Handle liefern, wenn der Inhalt den Arbeitsbedarf des Modells übersteigt. Große untypisierte Ergebnisse erhöhen Kosten und erschweren es, Prompt-Injektionen in abgerufenen Daten zu isolieren. Markieren Sie Tool-Daten in der Laufzeit als nicht vertrauenswürdigen Inhalt, selbst wenn sie aus Ihrer eigenen Datenbank stammen; gespeicherter Text kann ursprünglich von einem Angreifer kommen.

Schwärzen Sie im Adapter, bevor das Ergebnis in den Modellkontext gelangt. Die Berechtigung zum Aufruf von get_customer erlaubt nicht automatisch die Offenlegung jeder Kundenspalte. Definieren Sie eine Ergebnisansicht für die Aufgabe und halten Sie Geheimnisse, interne Kennzeichen und unbeteiligte persönliche Daten aus dem Schema heraus. Die Ausgabevalidierung schützt diese Ansicht dann vor Regressionen.

Geben Sie für lange Operationen eine Operationsressource mit einem endlichen Zustands-Enum wie queued, running, succeeded, failed oder cancelled zurück. Fragen Sie sie über ein Lese-Tool ab. Halten Sie keinen Modellaufruf offen, während eine Bereitstellung oder Migration läuft, und lassen Sie den Agenten Erfolg nicht aus verstrichener Zeit ableiten.

Wiederholung, Abbruch und Nebenläufigkeit brauchen erklärte Semantik

Ein Tool-Register sollte neben Ein- und Ausgabeschemas auch das Betriebsverhalten beschreiben. Halten Sie mindestens fest, ob das Tool liest oder schreibt, ob identische Aufrufe sicher wiederholt werden können, ob es Idempotenz unterstützt, welche Freigaberichtlinie gilt und wie ein Abbruch funktioniert. Das sind Regeln für den Ausführer, keine Prosahinweise an das Modell.

Ein Abbruch muss präzise sein. Das Stoppen eines Agentenlaufs kann künftige Tool-Aufrufe verhindern, aber eine von einem anderen Dienst bereits angenommene Anfrage nicht automatisch rückgängig machen. Ein Abbruch-Endpunkt sollte melden, ob die Operation gestoppt wurde, schon abgeschlossen war oder nicht unterbrochen werden kann. Gibt es eine Kompensation, stellen Sie sie als eigenen Schreibvorgang mit eigener Vorschau und Freigabe bereit. Nennen Sie eine Kompensation nicht Rollback, wenn sie ein weiteres Geschäftsereignis erzeugt.

Nebenläufigkeitsgrenzen gehören auf mehrere Ebenen. Begrenzen Sie Aufrufe pro Lauf, damit eine Planungsschleife keine API überflutet. Begrenzen Sie Aufrufe pro Mandant, damit ein beschäftigter Ablauf andere nicht verdrängt. Serialisieren Sie auf Ressourcenebene, wenn zwei freigegebene Schreibvorgänge am selben Datensatz kollidieren würden. Der vorhandene Dienst bleibt für Transaktionen und Sperren verantwortlich; die Agentenlaufzeit ersetzt keine Datenbankkorrektheit.

Zeitüberschreitungen sollten das Verhalten des Tools ausdrücken. Eine Zwei-Sekunden-Suche und eine lange numerische Konvertierung sollten nicht dieselbe willkürliche Frist haben. Die agentische Plattform von CodeHero liest ganze Legacy-Codebasen parallel, während Parität gegen aufgezeichneten Produktionsverkehr geprüft wird; eine solche Last braucht begrenzte Operationen und einen ausdrücklichen Abschlusszustand statt Vermutungen im Gespräch.

Fehler wegen Ratenbegrenzung sollten sagen, wann ein neuer Versuch Erfolg haben kann, doch die Laufzeit muss weiterhin Frist und Freigabegültigkeit des Laufs beachten. Läuft ein freigegebener Vorschlag während der Wartezeit ab, muss der nächste Aufruf scheitern und eine neue Freigabe anfordern. Bequemlichkeit steht nicht über der Zustimmungsgrenze.

Vertragstests finden Fehler, die Prompt-Tests übersehen

Eine Prompt-Auswertung kann zeigen, ob das Modell gewöhnlich das richtige Tool auswählt. Vertragstests beweisen, dass der falsche Aufruf nicht ausgeführt werden kann. Sie brauchen beides, doch die zweite Gruppe schützt die Produktion, wenn sich Modell, Prompt oder Tool-Beschreibung ändern.

Bauen Sie Fixtures aus echten Grenzfällen. Testen Sie für jedes Tool die kleinste gültige Anfrage, unbekannte Felder, fehlende Pflichtfelder, falsche Union-Zweige, Grenzen, veraltete Versionen, abgelaufene Freigaben, einen Genehmigenden ohne Befugnis, doppelte Idempotenzschlüssel und einen gültigen Schlüssel mit veränderten Argumenten. Prüfen Sie Ausgabevalidierung und Schwärzung genauso sorgfältig.

Ein kompakter Vertragstest kann so aussehen:

GIVEN proposal p_7f31 targets customer C-1842 version 17
AND the current customer version is 18
WHEN commit_address_change.v2 executes with idempotency key run9:p_7f31
THEN no address is changed
AND the result code is VERSION_CONFLICT
AND the proposal remains unconsumed

Die letzte Zusicherung ist wichtig. Verbraucht ein Konflikt die Freigabe, braucht der Ablauf nach der Neuplanung eine neue Freigabe, was korrekt sein kann. Darf dieselbe Freigabe laut Ihrer Richtlinie einen vorübergehenden Dienstfehler überleben, definieren Sie das getrennt. Tests zwingen das Team, diese Unterscheidung zu klären, statt sie während eines Vorfalls zu entdecken.

Testen Sie den Dispatcher als feindliche Grenze. Fordern Sie ein nicht registriertes Tool, ein Schreib-Tool in einem reinen Leselauf, eine alte Schemaversion, ein übergroßes Argumentobjekt und Zeichenketten mit Anweisungen an die Laufzeit an. Der Dispatcher sollte Daten parsen, Grenzen durchsetzen und nur einen registrierten Handler aufrufen. Er darf nie modellgenerierten Code auswerten oder einen Methodennamen dynamisch zusammensetzen.

Bewahren Sie auch eine kleine Menge vollständiger Ablaufspuren auf. Erfassen Sie Tool-Katalog, Modellanfrage, vorgeschlagene Aufrufe, Validierungsentscheidungen, Freigaben, Dienstergebnisse und Endantwort ohne sensible Werte. Spielen Sie diese Spuren nach Schemaänderungen erneut ab. Der genaue Wortlaut darf variieren, aber erlaubte Wirkungen und Invarianten müssen fest bleiben.

Vertragstests sollten außerdem den Katalog selbst fixieren. Speichern Sie für jede Laufzeitrolle eine erwartete Liste aus Tool-Namen, Versionen, Wirkungsklassen und Freigaberichtlinien. Ein neu registrierter Schreibvorgang scheitert dann in der Prüfung, wenn jemand die Richtlinie vergisst. Eine vermeintliche Leserolle scheitert, wenn ihr Katalog eine Commit-Operation erhält. So erkennen Sie Berechtigungsdrift, bevor ein Auswertungs-Prompt zufällig das neue Tool auswählt.

Erzeugen Sie ungültige Fälle systematisch, aber halten Sie den Generator innerhalb verstandener Schemabegriffe. Probieren Sie bei einer Pflichtzeichenkette Weglassen, leeren Text, einen zu großen Wert und den falschen primitiven Typ. Kombinieren Sie bei einer Union Felder beider Zweige und verwenden Sie einen unbekannten Diskriminator. Testen Sie bei Zahlen die exakten Grenzen und den jeweils nächsten Wert außerhalb. Es geht darum, für jede erklärte Grenze einen ausführbaren Ablehnungspfad nachzuweisen.

Produktionstelemetrie sollte konkrete Fragen beantworten, ohne sensible Nutzlasten zu speichern. Zählen Sie Aufrufe nach Tool und Schemaversion, Validierungsfehler nach Code und Feld, Freigabeentscheidungen, Konflikte, mehrdeutige Ergebnisse, Wiederholungen nach erklärter Klasse und Ausgabefehler. Ein plötzlicher Anstieg unbekannter Felder bedeutet oft, dass Prompt oder Client dem Register vorausgeeilt sind. Häufige Versionskonflikte können auf zu lange gültige Vorschläge oder zu frühes Lesen hinweisen. Diese Signale zeigen, ob Schema, Tool-Beschreibung oder Ablauf geändert werden sollte.

Behandeln Sie Validierungsfehler als Produktfeedback und nicht als Text, den Sie automatisch überdecken. Liefert das Modell wiederholt email an ein Tool, das nur customer_id akzeptiert, entscheiden Sie, ob die Suche in ein eigenes Lese-Tool gehört oder der Schreibvorgang eine stabile alternative Kennung annehmen sollte. Fügen Sie nicht still optionale Felder hinzu, bis die Aufrufe bestehen. Jedes neue Feld erweitert die Operation und braucht eigene Entscheidungen zu Berechtigung, Schwärzung und Tests.

Injizieren Sie Fehler rund um den Ausführer. Trennen Sie die Verbindung nach dem Commit des Dienstes, liefern Sie einen fehlerhaften Erfolgstext, verzögern Sie eine Freigabe bis zum Ablauf, lassen Sie zwei Vorschläge um dieselbe Version konkurrieren und machen Sie den Statusendpunkt vorübergehend unerreichbar. Prüfen Sie, dass die Laufzeit bei fehlenden Belegen ein unbekanntes Ergebnis meldet. Eine erfundene Erfolgsmeldung kann in einer Auswertung überzeugend wirken, deshalb muss die Zusicherung den gespeicherten Dienstzustand statt nur den letzten Satz prüfen.

Testen Sie schließlich, dass Freigabeanzeige und Commit denselben kanonischen Vorschlag verwenden. Stellen Sie die Freigabe aus gespeicherten kanonischen Daten dar, genehmigen Sie sie und verändern Sie vor dem Commit jede vom Agenten kontrollierte Kopie der Argumente. Die ausgeführte Wirkung muss identisch mit der angezeigten bleiben. Ist dieser Test schwer zu schreiben, hängt die Freigabegrenze wahrscheinlich vom Gesprächszustand ab, wo sie gerade nicht hingehört.

Die sichere Vorgabe ist eine kleinere Tool-Oberfläche

Beginnen Sie mit dem kleinsten Katalog, der einen echten Ablauf abschließt. Ein Tool verdient seinen Platz, wenn seine Eingabe begrenzt, seine Ausgabe validiert, seine Wirkung klassifiziert und seine Fehler dargestellt werden können, ohne dass das Modell raten muss. Können Sie diese Teile nicht definieren, ist die API noch nicht bereit, ein Agenten-Tool zu werden.

Widerstehen Sie dem beliebten Rat, jeden internen Endpunkt offenzulegen und das Modell frei planen zu lassen. Teams mögen ihn, weil die erste Vorführung schnell entsteht. In der Produktion verschiebt er API-Archäologie, Berechtigungswahl und Fehlerauslegung in eine probabilistische Komponente. Das Modell verbraucht dann Tokens, um Regeln neu zu entdecken, die Ihre Dienste längst kennen, und ein plausibler Fehler kann eine Schreibgrenze überschreiten.

Ein schmaler Tool-Katalog macht den Agenten nicht weniger fähig. Er macht Fähigkeiten ausdrücklich. Ergänzen Sie ein Tool, wenn Protokolle eine fehlende Operation zeigen, und nicht wenn ein Prompt einen weiteren Absatz darüber erhält, wie eine fremde Aktion durch einen generischen Endpunkt zu pressen sei. Versionieren Sie den Vertrag, hängen Sie eine Richtlinie an und geben Sie dem Ausführer ein typisiertes Ergebnis.

Für einen Schreibvorgang gilt ein höherer Maßstab. Fordern Sie einen kanonischen Vorschlag, eine an Hash und Zielversion gebundene Freigabe, ein Idempotenzprotokoll und ein Ergebnis, das die Änderung belegt. Machen Sie unbekannte Ergebnisse für einen Bediener sichtbar. Ein pausierter Ablauf ist lästig; ein Agent, der selbstsicher den falschen Produktionszustand meldet, ist teuer.

Typisierte Tools sind der Punkt, an dem ein Agent keine Chat-Oberfläche um privilegierte Zugangsdaten mehr ist, sondern eine kontrollierbare Softwarekomponente wird. Lassen Sie das Denken im Modell. Halten Sie Berechtigung und Wahrheit an der Grenze.