Die meisten Agenten-Codebasen enthalten eine Datei, die niemand gerne pflegt. Sie enthält vierzig Tool-Definitionen, jede davon ein handgeschriebenes JSON-Schema, das einen Endpunkt beschreibt, der bereits irgendwo anders ein Schema hat. Das API-Team liefert ein neues Pflichtfeld aus, die Spezifikation wird aktualisiert, die Dokumentation wird aktualisiert, und der Agent sendet weiterhin die alte Nutzlast, bis jemand die 400er bemerkt.
Sie haben bereits eine maschinenlesbare Beschreibung jedes Endpunkts. Es ist das OpenAPI-Dokument. Die Aufgabe ist, dieses in Tool-Definitionen umzuwandeln, die das Modell aufrufen kann, und die beiden automatisch statt nur aus dem Gedächtnis synchron zu halten.
Dieser Leitfaden behandelt, wie OpenAPI-Operationen Tool-Schemas zugeordnet werden, was der Generator dabei korrigieren muss, wie man eine 200-Endpunkt-Spezifikation auf etwas reduziert, das ein Modell verarbeiten kann, und wie man testet, ob die generierten Tools funktionieren. Wenn Sie früher im Stack sind, erläutert unser Beitrag darüber, ob man noch ein API-Tool benötigt, wenn Agenten den Code schreiben, den weiteren Kontext.
Apidog ist hier wichtig, denn die Spezifikation muss korrekt sein, bevor etwas, das daraus generiert wird, korrekt sein kann. Eine Tool-Definition erbt jede Lücke im Dokument, aus dem sie stammt.
Die Kosten handgeschriebener Tool-Definitionen
Das handschriftliche Erstellen von Tools fühlt sich bei fünf Endpunkten noch gut an. Irgendwann um zwanzig Endpunkte herum ist es aus drei Gründen nicht mehr gut.
Definitionen driften auseinander. Die Spezifikation wird aus Code generiert oder vom API-Team gepflegt. Die Tool-Datei wird von demjenigen gepflegt, der den Agenten gebaut hat. Nichts verbindet sie, so dass sie leise auseinanderlaufen, und das erste Symptom ist ein Agent, der „plötzlich“ nicht mehr funktioniert.
Beschreibungen werden dünn. Wenn eine Person vierzig Schemata von Hand schreibt, bekommen die letzten zwanzig einzeilige Beschreibungen. Modelle wählen Tools, indem sie diese Beschreibungen lesen, sodass knapper Text die Tool-Auswahl direkt verschlechtert. Unser Beitrag zum Design von Tool-Schemas für Agenten geht tiefer darauf ein, warum die Formulierung so viel Gewicht hat.
Fehler sind bis zur Laufzeit unsichtbar. Ein handgeschriebenes Schema, das besagt, ein Feld sei ein String, obwohl die API eine Ganzzahl erwartet, erzeugt einen 422, wenn der Agent es zum ersten Mal in Produktion bei einer echten Aufgabe versucht.
Die Generierung aus der Spezifikation behebt alle drei Probleme auf einmal. Es gibt eine einzige Quelle der Wahrheit, Beschreibungen stammen aus demselben Text, den Ihre Dokumentation verwendet, und Typen stammen aus demselben Schema, anhand dessen der Server validiert.
Wie eine OpenAPI-Operation zu einem Tool wird
Die Zuordnung ist direkter, als es aussieht. Nehmen wir eine einzelne Operation:
paths:
/orders/{orderId}/refund:
post:
operationId: refundOrder
summary: Refund an order
description: >
Issues a full or partial refund against a completed order.
Refunds are irreversible. Partial refunds require an amount
no greater than the remaining refundable balance.
parameters:
- name: orderId
in: path
required: true
schema: { type: string }
description: The order to refund.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [reason]
properties:
amount:
type: integer
description: Amount in cents. Omit for a full refund.
reason:
type: string
enum: [duplicate, fraudulent, requested_by_customer]
Die Tool-Definition, die daraus resultiert:
{
"name": "refundOrder",
"description": "Issues a full or partial refund against a completed order. Refunds are irreversible. Partial refunds require an amount no greater than the remaining refundable balance.",
"input_schema": {
"type": "object",
"required": ["orderId", "reason"],
"properties": {
"orderId": { "type": "string", "description": "The order to refund." },
"amount": { "type": "integer", "description": "Amount in cents. Omit for a full refund." },
"reason": { "type": "string", "enum": ["duplicate", "fraudulent", "requested_by_customer"] }
}
}
}
Vier Regeln erledigen den größten Teil der Arbeit:
operationIdwird zum Tool-Namen. Wenn eine Operation keineoperationIdhat, generieren Sie eine stabile aus Methode plus Pfad und fügen Sie diese dann der Spezifikation hinzu.- Pfad-, Abfrage- und Body-Parameter werden zu einem einzigen Eigenschaftenobjekt zusammengefasst. Das Modell kümmert sich nicht darum, wo ein Wert im Wire-Format transportiert wird. Ihr Executor tut dies, daher halten Sie eine Nebentabelle, die festhält, welcher Parameter wohin gehört.
summaryplusdescriptionwird zur Tool-Beschreibung. Beides, zusammengefügt. Die Zusammenfassung allein ist meist zu knapp, um die Auswahl zu leiten.- Erforderliche Arrays werden zusammengeführt. Ein erforderlicher Pfadparameter und ein erforderliches Body-Feld landen beide in derselben
required-Liste.
Der Executor ist die andere Hälfte, und er ist klein:
def execute(tool_name, args, spec_index, http):
op = spec_index[tool_name] # method, path template, param locations
path = op.path
query, body = {}, {}
for name, value in args.items():
location = op.locations[name] # "path" | "query" | "header" | "body"
if location == "path":
path = path.replace("{" + name + "}", str(value))
elif location == "query":
query[name] = value
elif location == "body":
body[name] = value
return http.request(op.method, path, params=query, json=body or None)
Das ist die gesamte Brücke. Alles andere ist Bereinigung auf dem Weg.
Was der Generator beheben muss
Ein naives Ablegen der Spezifikation in Tool-Schemas erzeugt Tools, die Modelle schlecht handhaben. Fünf Anpassungen sind wichtig.
$ref-Pointer auflösen. Die meisten Tool-Calling-APIs akzeptieren eine Untermenge von JSON Schema und folgen Referenzen in einem components-Abschnitt nicht. Fügen Sie sie inline ein. Achten Sie auf rekursive Schemas, die durch Inline-Einfügung endlos erweitert würden; brechen Sie die Rekursion bei einer festen Tiefe ab und beschreiben Sie die tiefere Struktur in Prosa.
Nicht unterstützte Schlüsselwörter entfernen. oneOf, allOf, discriminator und nullable sind in Spezifikationen üblich und werden von Tool-Schemas schlecht unterstützt. Führen Sie allOf durch Zusammenführen von Eigenschaften zusammen. Bei oneOf wählen Sie entweder die dominante Variante oder teilen die Operation in zwei Tools auf, eines pro Form. Diese zweite Option führt meist ohnehin zu einer besseren Tool-Auswahl.
Tiefe Verschachtelungen abflachen. Eine drei Ebenen tiefe Body-Struktur ist für ein Modell schwer korrekt auszufüllen. Wenn Ihre Erstellungsanfrage für eine Bestellung customer.address.postal_code verschachtelt, sollten Sie eine flachere Tool-Oberfläche in Betracht ziehen und die verschachtelte Form im Executor wieder zusammensetzen.
Antwortschemata beschneiden. Tool-Definitionen beschreiben Eingaben. Das vollständige Antwortschema gehört nicht in die Definition, und dessen Aufnahme verschwendet Kontext. Wie die Antwort aussieht, ist wichtig, wenn das Ergebnis zurückkommt, und das ist ein separates Problem, das in unserem Beitrag zum Thema Halten von API-Antworten im Kontextfenster des Agenten behandelt wird.
Sicherheitsflags beibehalten. Schreiboperationen sollten markiert werden, damit Ihr Executor sie durch eine Genehmigungsschleuse leiten kann. Wenn Ihre Spezifikation eine Erweiterung wie x-agent-requires-approval verwendet, lesen und beachten Sie diese. Kombinieren Sie dies mit den Mustern in unserem Leitfaden zu AI-Agenten-Schutzmechanismen.
Geben Sie dem Modell nicht alle 200 Endpunkte
Das größte praktische Problem ist nicht die Konvertierung. Es ist das Volumen. Eine ausgereifte API hat Hunderte von Operationen, und das Einfügen aller in die Tool-Liste führt zu zwei Fehlern gleichzeitig: Der Kontext füllt sich mit Schemas, bevor die Aufgabe beginnt, und die Auswahlgenauigkeit sinkt, weil das Modell zwischen nahezu identischen Optionen wählt.
Drei Wege, es zu reduzieren, ungefähr in der Reihenfolge ihrer Wirksamkeit.
Filtern nach Tag. OpenAPI-Operationen tragen Tags, und Tags entsprechen normalerweise Produktbereichen. Ein Agent, der Rückerstattungen bearbeitet, benötigt die Tags orders und payments, nicht admin oder analytics. Dies ist ein einzeiliger Filter und entfernt typischerweise den größten Teil der Oberfläche.
Eine Zulassungsliste kuratieren. Schreiben Sie die Operationen auf, die dieser Agent aufrufen darf, nach operationId, und generieren Sie nur diese. Dies dient auch als Sicherheitskontrolle, da ein Agent, der kein Tool für einen Endpunkt hat, diesen nicht versehentlich aufrufen kann. Unser Beitrag zum Verhindern, dass KI-Agenten Ihre API nuken plädiert genau für diese Art von enger Oberfläche.
Tools bei Bedarf abrufen. Für sehr große APIs indizieren Sie die Operationen und wählen Sie pro Zug eine Handvoll basierend auf der Aufgabe aus. Dies fügt einen Abrufschritt und eigene Fehlermodi hinzu, daher sollten Sie dies nur dann in Betracht ziehen, wenn Filtern und Kuratieren nicht mehr ausreichen.
Es gibt auch den Protokollweg. Das Model Context Protocol standardisiert, wie ein Server Tools einem Client zur Verfügung stellt, und ein MCP-Server, der von Ihrem OpenAPI-Dokument unterstützt wird, bietet Ihnen einen Integrationspunkt statt einen pro Framework. Unser Erklärer was MCP ist behandelt das Modell, und den Bau eines MCP-Servers mit Apidog behandelt den Bau.
Die Spezifikation muss zuerst stimmen
Die Generierung verlagert das Qualitätsproblem stromaufwärts. Eine vage Beschreibung in Ihrem OpenAPI-Dokument wird zu einer vagen Tool-Beschreibung, und das Modell wählt den falschen Endpunkt. Ein optionales Feld, das der Server tatsächlich benötigt, wird zu einem Tool, das der Agent beim ersten Versuch falsch aufruft.
Überprüfen Sie also die Spezifikation aus der Sicht eines Agenten, bevor Sie etwas generieren:
- Jede Operation hat eine
operationId, die wie ein Verb plus ein Substantiv gelesen wird. - Jede Operation hat eine Beschreibung, die besagt, was sie tut, was sie ändert und wann sie nicht verwendet werden sollte. „Löscht einen Benutzer“ ist nicht genug. „Löscht einen Benutzer und alle seine Sitzungen dauerhaft. Kann nicht rückgängig gemacht werden. Verwenden Sie deactivateUser, um den Zugriff vorübergehend zu deaktivieren.“ ist es.
- Jeder Parameter hat eine Beschreibung mit Einheiten und Format.
amountist mehrdeutig. „Betrag in Cent, mindestens 50“ ist es nicht. - Enums werden deklariert statt in Prosa beschrieben, sodass das Modell einen geschlossenen Satz erhält, anstatt zu raten.
- Required ist genau. Spezifikationen neigen dazu, alles als optional zu kennzeichnen, was Validierungsfehler in die Laufzeit verschiebt.
Dies ist eine normale Spezifikationshygiene und zahlt sich doppelt aus, denn derselbe Text treibt Ihre veröffentlichten Dokumente an. In Apidog stammen die Spezifikation, die Dokumentation, der Mock-Server und die Tests aus einem Projekt, sodass die Straffung einer Beschreibung alle gleichzeitig verbessert. Unser Leitfaden zum Verwalten der API-Versionierung in Apidog behandelt die andere Hälfte, um generierte Tools im Laufe der Zeit ehrlich zu halten.
Teilen Sie das Toolset, kopieren Sie es nicht
Ein generiertes Toolset ist eine Konfiguration, und eine Konfiguration, die im Checkout eines Entwicklers lebt, driftet auf die gleiche Weise ab wie handgeschriebene Schemas. Die Filterliste, die Whitelist und die fixierte Spezifikationsversion sollten gemeinsame Artefakte sein, die zusammen mit der Spezifikation, aus der sie stammen, versioniert werden.
Einige Plattformen machen dies zur Standardeinheit. In Sharkly ist ein Agent eine gespeicherte Arbeitskonfiguration statt einer einmaligen Eingabeaufforderung: seine Anweisungen, Runtime, Skills, Repositories und Ausführungseinstellungen reisen mit ihm und können über einen Space hinweg geteilt werden, sodass ein funktionierendes Tool-Setup etwas wird, das ein Team wiederverwendet, anstatt etwas, das jede Person neu aufbaut. Die zugrunde liegende Laufzeit ist immer noch Claude Code, Codex oder was auch immer Sie bereits verwenden. Was sich ändert, ist, dass die Konfiguration darum herum nicht mehr lokal ist.
Testen generierter Tools
Generierte Tools versagen auf Weisen, die handgeschriebene nicht tun, daher testen Sie sowohl die Generierung als auch die Aufrufe.
Beginnen Sie mit einer Schema-Round-Trip-Prüfung. Erstellen Sie für jedes generierte Tool ein gültiges Beispiel aus dem Schema und senden Sie es. Alles, was 400 oder 422 zurückgibt, bedeutet, dass das Tool-Schema und der Server nicht übereinstimmen, und die Spezifikation ist das, was behoben werden muss.
Testen Sie dann die Auswahl. Schreiben Sie eine kleine Reihe von Aufgabenaufforderungen mit einem bekannten korrekten Tool, führen Sie sie aus und notieren Sie, welches Tool das Modell ausgewählt hat. Dies ist eine kostengünstige Regressions-Suite, die den Tag abfängt, an dem jemand eine Operation umbenennt oder eine Beschreibung kürzt. Da die Ausgabe nicht deterministisch ist, bestätigen Sie den Tool-Namen und nicht die genauen Argumente, ähnlich wie in unserem Leitfaden zum Testen nicht-deterministischer Agenten.
Führen Sie den Agenten schließlich vor jeglichem Live-Betrieb gegen Mocks aus. Ein Mock-Server, der aus derselben Spezifikation generiert wird, liefert Ihnen realistische Antworten ohne Nebenwirkungen und ermöglicht es Ihnen, 500er und Timeouts einzuschleusen, die Ihre Wiederholungslogik eigentlich behandeln sollte.
Was das für Sie bedeutet
Die Spezifikation ist der Vertrag, und die Tool-Liste sollte eine Projektion davon sein, keine parallel von Hand gepflegte Kopie. Generieren Sie die Tools, filtern Sie sie streng, halten Sie die Beschreibungen ehrlich und testen Sie sowohl die Formen als auch die Auswahl.
Beginnen Sie mit dem Export Ihres OpenAPI-Dokuments und zählen Sie die Operationen, die keine Beschreibung haben. Diese Zahl zeigt an, wie viel Arbeit zwischen Ihnen und vertrauenswürdigen Agenten-Tools liegt. Laden Sie Apidog herunter, wenn Sie die Spezifikation, Mocks und Tests an einem Ort haben möchten, während Sie es beheben.
Häufig gestellte Fragen
Kann ich Tools aus einem Swagger 2.0 Dokument generieren? Ja, aber konvertieren Sie es zuerst in OpenAPI 3.x. Das 2.0 Body-Modell unterscheidet sich ausreichend, so dass Generatoren es inkonsistent handhaben, und 3.x ist das, worauf aktuelle Tools abzielen. Das OpenAPI Specification Repository dokumentiert die Unterschiede.
Wie viele Tools kann ein Modell gleichzeitig verarbeiten? Die Genauigkeit beginnt sich weit vor der technischen Grenze zu verschlechtern, und die praktische Obergrenze liegt normalerweise bei einigen Dutzend. Betrachten Sie jede Liste, die darüber hinausgeht, als Signal, nach Tags zu filtern oder eine Zulassungsliste zu kuratieren, anstatt als eine zu testende Grenze.
Sollen Tool-Namen exakt mit operationId übereinstimmen? Ja, wenn die operationId lesbar ist. Dies ermöglicht eine direkte Zuordnung vom Tool-Aufruf zurück zur Spezifikationsoperation, was das Nachverfolgen und Debuggen erheblich vereinfacht. Benennen Sie in der Spezifikation um, wenn der Name schlecht ist, nicht im Generator.
Was ist mit GraphQL-APIs? Dieselbe Idee gilt mit einer anderen Quelle: Introspektieren Sie das Schema und generieren Sie ein Tool pro Abfrage oder Mutation. Das Volumenproblem ist schlimmer, da ein GraphQL-Schema mehr Oberfläche offenlegt, daher ist das Filtern noch wichtiger.
Muss ich immer noch Tools von Hand schreiben? Ein paar. Verbund-Tools, die mehrere Aufrufe zu einer Aktion verketten, und Tools, die etwas anderes als HTTP umschließen, werden immer noch manuell geschrieben. Der Punkt ist, dass die routinemäßigen Ein-Endpunkt-Wrapper keine Handarbeit mehr sind.
Wie verhindere ich, dass der Agent während des Tests Schreib-Endpunkte aufruft? Generieren Sie einen schreibgeschützten Toolset für Testläufe, indem Sie nach HTTP-Methode filtern, und verweisen Sie den Agenten auf einen Mock für alles, was schreibt. Unser Beitrag dazu, warum Agenten Mocks und nicht die Produktion treffen sollten, behandelt das Setup.