OpenAPI für KI-Agenten-Tools: Manuelle Wrapper vermeiden

OpenAPI-Spezifikationen automatisch in Agent-Tools umwandeln

Die meisten Agenten-Codebasen enthalten eine Datei, die niemand gerne pflegt: vierzig Tool-Definitionen mit handgeschriebenen JSON-Schemas für Endpunkte, die bereits an anderer Stelle beschrieben sind. Das API-Team liefert ein neues Pflichtfeld aus, aktualisiert die Spezifikation und Dokumentation – doch der Agent sendet weiter die alte Nutzlast, bis jemand die 400-Fehler bemerkt.

Apidog heute ausprobieren

Sie haben bereits eine maschinenlesbare Beschreibung jedes Endpunkts: das OpenAPI-Dokument. Die Aufgabe besteht darin, daraus Tool-Definitionen zu erzeugen, die ein Modell aufrufen kann, und Spezifikation und Agent automatisch synchron zu halten.

Dieser Leitfaden zeigt:

• wie OpenAPI-Operationen auf Tool-Schemas abgebildet werden,
• welche Anpassungen ein Generator benötigt,
• wie Sie eine API mit 200 Endpunkten auf eine modellfreundliche Oberfläche reduzieren,
• wie Sie generierte Tools testen.

Wenn Sie früher im Stack ansetzen, bietet der Beitrag Brauchen Sie noch ein API-Tool, wenn Agenten Code schreiben? zusätzlichen Kontext.

Apidog ist dabei relevant: Die Spezifikation muss korrekt sein, bevor daraus korrekte Tools entstehen können. Jede Lücke im OpenAPI-Dokument wird an die Tool-Definition vererbt.

Die Kosten handgeschriebener Tool-Definitionen

Bei fünf Endpunkten fühlt sich das Erstellen von Tools noch überschaubar an. Ab ungefähr zwanzig Endpunkten entstehen drei Probleme.

Definitionen driften auseinander

Die Spezifikation wird aus Code generiert oder vom API-Team gepflegt. Die Tool-Datei pflegt dagegen die Person, die den Agenten gebaut hat. Ohne Verbindung laufen beide still auseinander. Das erste Symptom ist ein Agent, der scheinbar plötzlich nicht mehr funktioniert.

Beschreibungen werden zu knapp

Wer vierzig Schemata von Hand schreibt, versieht die letzten zwanzig oft nur noch mit Einzeilern. Modelle wählen Tools anhand ihrer Beschreibungen. Knappere Beschreibungen verschlechtern daher direkt die Tool-Auswahl. Der Beitrag Design von Tool-Schemas für Agenten erklärt, warum die Formulierung so wichtig ist.

Fehler werden erst zur Laufzeit sichtbar

Ein handgeschriebenes Schema, das ein Feld als String statt als Ganzzahl beschreibt, erzeugt beim ersten echten Aufruf in Produktion einen 422-Fehler.

Die Generierung aus der Spezifikation löst alle drei Probleme:

• eine einzige Quelle der Wahrheit,
• Beschreibungen aus demselben Text wie die API-Dokumentation,
• Typen aus demselben Schema, das der Server zur Validierung verwendet.

Wie eine OpenAPI-Operation zu einem Tool wird

Die Zuordnung ist direkter, als sie zunächst wirkt. Nehmen wir diese 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]

Daraus entsteht beispielsweise folgende Tool-Definition:

{
  "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:

1. operationId wird zum Tool-Namen. Fehlt sie, generieren Sie einen stabilen Namen aus HTTP-Methode und Pfad und ergänzen Sie ihn anschließend in der Spezifikation.
2. Pfad-, Query- und Body-Parameter werden zusammengeführt. Für das Modell ist nicht entscheidend, wo ein Wert im Wire-Format übertragen wird. Der Executor übernimmt diese Zuordnung über eine Nebentabelle.
3. summary und description werden zur Tool-Beschreibung. Die Zusammenfassung allein ist meist zu knapp, um die Auswahl zuverlässig zu steuern.
4. Pflichtfelder werden zusammengeführt. Ein erforderlicher Pfadparameter und ein erforderliches Body-Feld landen in derselben required-Liste.

Der Executor ist die andere Hälfte der Brücke:

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 Kernlogik. Alles Weitere ist Bereinigung und Validierung.

Was der Generator korrigieren muss

Eine OpenAPI-Spezifikation unverändert in Tool-Schemas zu kopieren, führt oft zu Tools, die Modelle schlecht verwenden können. Fünf Anpassungen sind besonders wichtig.

$ref-Pointer auflösen

Viele Tool-Calling-APIs unterstützen nur eine Teilmenge von JSON Schema und folgen keinen Referenzen in components. Lösen Sie Referenzen daher inline auf.

Achten Sie auf rekursive Schemas: Eine vollständige Inline-Auflösung kann endlos wachsen. Begrenzen Sie die Tiefe und beschreiben Sie die tiefere Struktur stattdessen in Prosa.

Nicht unterstützte Schlüsselwörter entfernen

oneOf, allOf, discriminator und nullable sind in Spezifikationen üblich, werden von Tool-Schemas aber oft nur unvollständig unterstützt.

• Führen Sie allOf durch Zusammenführen der Eigenschaften zusammen.
• Wählen Sie bei oneOf entweder die dominante Variante.
• Oder teilen Sie die Operation in zwei Tools auf – meist verbessert das auch die Tool-Auswahl.

Tiefe Verschachtelungen abflachen

Eine drei Ebenen tiefe Body-Struktur ist für ein Modell schwer korrekt auszufüllen. Wenn eine Bestellung beispielsweise customer.address.postal_code benötigt, kann eine flachere Tool-Oberfläche sinnvoll sein. Setzen Sie die verschachtelte Form im Executor wieder zusammen.

Antwortschemata entfernen

Tool-Definitionen beschreiben Eingaben. Das vollständige Antwortschema gehört nicht in die Definition und verschwendet Kontext. Wie die Antwort nach dem Aufruf verarbeitet wird, ist ein separates Thema. Dazu gehört auch der Beitrag API-Antworten im Kontextfenster des Agenten halten.

Sicherheitsflags beibehalten

Schreiboperationen sollten markiert werden, damit der Executor sie durch eine Genehmigungsschleuse leiten kann. Wenn Ihre Spezifikation Erweiterungen wie x-agent-requires-approval nutzt, muss der Generator sie übernehmen.

Kombinieren Sie diese Markierungen mit den Mustern aus dem Leitfaden zu AI-Agenten-Schutzmechanismen.

Geben Sie dem Modell nicht alle 200 Endpunkte

Das größte praktische Problem ist nicht die Konvertierung, sondern das Volumen. Eine ausgereifte API kann Hunderte von Operationen enthalten. Werden alle als Tools übergeben, passiert gleichzeitig Folgendes:

• Der Kontext wird mit Schemas gefüllt, bevor die Aufgabe beginnt.
• Die Auswahlgenauigkeit sinkt, weil das Modell zwischen ähnlichen Optionen entscheiden muss.

Reduzieren Sie die Tool-Liste in dieser Reihenfolge:

1. Nach Tags filtern

OpenAPI-Operationen tragen Tags, die meist Produktbereiche abbilden. Ein Agent für Rückerstattungen benötigt beispielsweise orders und payments, nicht aber admin oder analytics.

Das ist ein einfacher Filter und entfernt typischerweise den größten Teil der Oberfläche.

2. Eine Zulassungsliste kuratieren

Definieren Sie anhand der operationId, welche Operationen dieser Agent aufrufen darf, und generieren Sie nur diese Tools.

Das ist zugleich eine Sicherheitskontrolle: Was nicht als Tool vorhanden ist, kann der Agent nicht versehentlich aufrufen. Der Beitrag Verhindern, dass KI-Agenten Ihre API nuken beschreibt dieses Prinzip ausführlicher.

3. Tools bei Bedarf abrufen

Bei sehr großen APIs können Sie Operationen indizieren und pro Lauf nur eine kleine Auswahl passend zur Aufgabe laden. Das führt allerdings einen zusätzlichen Abrufschritt und neue Fehlerquellen ein. Nutzen Sie diesen Ansatz erst, wenn Filtern und Kuratieren nicht mehr ausreichen.

4. Einen Protokollweg nutzen

Das Model Context Protocol standardisiert, wie Server Tools für Clients bereitstellen. Ein MCP-Server auf Basis Ihres OpenAPI-Dokuments bietet einen Integrationspunkt statt einer separaten Implementierung für jedes Framework.

Weitere Informationen finden Sie in den Beiträgen Was ist MCP? und MCP-Server mit Apidog und AI-Agenten bauen.

Die Spezifikation muss zuerst stimmen

Die Generierung verlagert das Qualitätsproblem stromaufwärts. Eine vage Beschreibung im OpenAPI-Dokument wird zu einer vagen Tool-Beschreibung. Ein Feld, das als optional markiert ist, obwohl der Server es tatsächlich verlangt, führt zu einem fehlerhaften Aufruf.

Prüfen Sie die Spezifikation deshalb aus der Perspektive eines Agenten:

• Jede Operation besitzt eine gut lesbare operationId, idealerweise als Verb plus Substantiv.
• Jede Operation beschreibt, was sie tut, was sie verändert und wann sie nicht verwendet werden sollte.
• Jeder Parameter enthält Beschreibung, Einheit und Format. amount ist mehrdeutig; „Betrag in Cent, mindestens 50“ ist eindeutig.
• Enums sind als Enums deklariert und nicht nur in Prosa erklärt.
• required ist exakt und entspricht der tatsächlichen Servervalidierung.

Beispiel für eine nützliche Beschreibung:

Löscht einen Benutzer und alle seine Sitzungen dauerhaft. Dieser Vorgang kann nicht rückgängig gemacht werden. Verwenden Sie deactivateUser, wenn der Zugriff nur vorübergehend deaktiviert werden soll.

Das ist normale Spezifikationshygiene und verbessert gleichzeitig Ihre veröffentlichten Dokumente. In Apidog stammen Spezifikation, Dokumentation, Mock-Server und Tests aus einem Projekt. Eine bessere Beschreibung verbessert daher alle vier Artefakte.

Der Beitrag API-Versionierung in Apidog verwalten behandelt, wie Sie generierte Tools langfristig mit der Spezifikation synchron halten.

Teilen Sie das Toolset, kopieren Sie es nicht

Ein generiertes Toolset ist eine Konfiguration. Wenn diese Konfiguration nur im Checkout eines Entwicklers liegt, driftet sie genauso wie ein handgeschriebenes Schema.

Versionieren Sie deshalb gemeinsam mit der zugrunde liegenden Spezifikation:

• Filter und Tags,
• die Zulassungsliste,
• die verwendete Spezifikationsversion,
• Sicherheits- und Genehmigungsflags.

Einige Plattformen machen die Konfiguration zur gemeinsamen Einheit. In Sharkly ist ein Agent beispielsweise eine gespeicherte Arbeitskonfiguration statt nur einer einmaligen Eingabeaufforderung. Anweisungen, Runtime, Skills, Repositories und Ausführungseinstellungen können über einen Space hinweg geteilt werden.

Die zugrunde liegende Runtime bleibt dabei Claude Code, Codex oder das von Ihnen eingesetzte System. Der Unterschied: Die Konfiguration darum herum ist nicht mehr an einen lokalen Checkout gebunden.

Generierte Tools testen

Generierte Tools können auf andere Weise fehlschlagen als handgeschriebene. Testen Sie deshalb sowohl die Generierung als auch die Aufrufe.

1. Schema-Roundtrip prüfen

Erzeugen Sie für jedes Tool ein gültiges Beispiel aus dem Schema und senden Sie es an den Server.

• 400- oder 422-Antworten zeigen, dass Tool-Schema und Server nicht übereinstimmen.
• Korrigieren Sie zuerst die Spezifikation, nicht nur das generierte Tool.

2. Tool-Auswahl testen

Erstellen Sie eine kleine Suite von Aufgabenaufforderungen mit jeweils einem bekannten korrekten Tool. Führen Sie sie aus und protokollieren Sie die Auswahl des Modells.

Bestätigen Sie den Tool-Namen, nicht die exakten Argumente. Die Ausgabe ist nicht deterministisch. Diese Suite erkennt Regressionen, wenn jemand eine Operation umbenennt oder eine Beschreibung kürzt. Weitere Hinweise bietet Testen nicht-deterministischer Agenten.

3. Gegen Mocks testen

Führen Sie den Agenten vor jedem Live-Betrieb gegen einen Mock-Server aus. Ein aus derselben Spezifikation generierter Mock-Server liefert realistische Antworten ohne Seiteneffekte.

Zusätzlich können Sie 500-Fehler und Timeouts einspielen und prüfen, ob Ihre Wiederholungslogik korrekt reagiert. Lesen Sie dazu auch Warum Agenten Mocks statt der Produktion aufrufen sollten.

Was das für Sie bedeutet

Die Spezifikation ist der Vertrag. Die Tool-Liste sollte eine Projektion dieses Vertrags sein, keine parallel gepflegte Kopie.

Gehen Sie so vor:

1. Exportieren Sie Ihr OpenAPI-Dokument.
2. Zählen Sie Operationen ohne Beschreibung oder operationId.
3. Korrigieren Sie die Spezifikation.
4. Generieren Sie die Tool-Schemas.
5. Filtern Sie sie strikt nach Aufgabe und Berechtigungen.
6. Testen Sie Schema, Tool-Auswahl und Fehlerverhalten gegen Mocks.

Wenn Sie Spezifikation, Mocks und Tests an einem Ort verwalten möchten, laden Sie Apidog herunter.

Häufig gestellte Fragen

Kann ich Tools aus einem Swagger-2.0-Dokument generieren?

Ja, konvertieren Sie es aber zuerst in OpenAPI 3.x. Das Body-Modell von Swagger 2.0 unterscheidet sich ausreichend, dass Generatoren es uneinheitlich behandeln. Aktuelle Tools zielen meist auf OpenAPI 3.x. Die Unterschiede sind im OpenAPI Specification Repository dokumentiert.

Wie viele Tools kann ein Modell gleichzeitig verarbeiten?

Die Genauigkeit verschlechtert sich meist lange vor der technischen Grenze. In der Praxis liegt die sinnvolle Obergrenze oft bei einigen Dutzend Tools.

Betrachten Sie größere Listen als Signal, nach Tags zu filtern oder eine Zulassungsliste zu kuratieren – nicht als technische Grenze, die Sie ausreizen sollten.

Müssen Tool-Namen exakt mit operationId übereinstimmen?

Ja, sofern die operationId lesbar ist. So lässt sich ein Tool-Aufruf direkt auf die Spezifikationsoperation zurückführen, was Nachverfolgung und Debugging vereinfacht.

Benennen Sie die Operation in der Spezifikation um, wenn der Name schlecht ist – nicht im Generator.

Was ist mit GraphQL-APIs?

Dieselbe Idee funktioniert mit einer anderen Quelle: Introspektieren Sie das Schema und generieren Sie ein Tool pro Query oder Mutation.

Das Volumenproblem ist bei GraphQL oft größer, weil ein Schema mehr Oberfläche offenlegt. Filtern ist daher besonders wichtig.

Muss ich weiterhin Tools von Hand schreiben?

Einige schon:

• Verbund-Tools, die mehrere Aufrufe zu einer Aktion verketten,
• Tools, die nicht HTTP, sondern andere Systeme umschließen,
• domänenspezifische Aktionen mit eigener Geschäftslogik.

Routinemäßige Ein-Endpunkt-Wrapper müssen jedoch keine Handarbeit mehr sein.

Wie verhindere ich Schreibzugriffe während des Tests?

Generieren Sie für Testläufe ein schreibgeschütztes Toolset, indem Sie nach HTTP-Methode filtern. Verweisen Sie den Agenten für alle Schreiboperationen auf einen Mock-Server.