API Spec Tools
OpenAPI-Spezifikationen werden zu aufrufbaren Agenten-Tools mit Authentifizierung, Wildcard-Referenzen und individueller Tool-Konfiguration.
Auf dieser Seite
Überblick
API Spec Tools importieren eine OpenAPI-Spezifikation (v3.x) und generieren aufrufbare Tools für Agenten. Statt für jeden API-Endpunkt Code für ein Custom Tool zu schreiben, erhält Connic eine Spezifikation und generiert daraus die Tools.
Importiere eine OpenAPI-Spezifikation und erhalte aufrufbare Tools. Jeder Endpunkt wird zu einem Tool, das Agenten aufrufen können.
Verwende Patterns wie api:my_api.* oder api:my_api.users_* im Agent YAML, um Gruppen von Tools zu referenzieren.
Integrierte Unterstützung für Bearer Token, API-Key und Basic Auth. Zugangsdaten werden sicher gespeichert und zur Laufzeit eingefügt.
API Spec Tool hinzufügen
Öffne in den Composer-Einstellungen des Projekts den Bereich API Spec Tools und klicke auf Add API Spec. Für jedes API Spec Tool sind folgende Angaben erforderlich:
| Feld | Beschreibung |
|---|---|
| Name | Ein Namespace-Identifier (nur Kleinbuchstaben und Unterstriche). Er wird zum Präfix für Tool-Referenzen im Agent YAML, etwa api:my_api.*. |
| Source | Lade eine OpenAPI-Spezifikation als JSON- oder YAML-Datei hoch oder gib eine URL an, von der die Spezifikation abgerufen wird. Spezifikationen aus URLs lassen sich aktualisieren. |
| Base URL | Überschreibt die in der Spezifikation definierte Server-URL, etwa für einen Staging- oder internen Endpunkt anstelle des Standardservers. |
| Authentication | Konfiguriere Zugangsdaten für die Ziel-API. Unterstützt Bearer Token, API-Key und Basic Auth. Die Zugangsdaten werden in jede Anfrage eingefügt, die der Agent stellt. |
Verweise über $ref dürfen keine Kreise bilden. Für ihre Auflösung gelten folgende Grenzen: 50 Verschachtelungsebenen, 100.000 Verarbeitungsschritte, 100.000 aufgelöste Knoten und ein Ergebnis von höchstens 8 MiB.
Tool-Namensgebung
Jeder Endpunkt der Spezifikation wird zu einem Tool. Ist in der Spezifikation eine operationId definiert, dient sie als Basisname. Sie wird in snake_case umgewandelt und das Aktionsverb ans Ende verschoben. Andernfalls wird der Name aus HTTP-Methode und Pfad abgeleitet.
Ohne operationId (pfadbasiert)
Häufige Pfadpräfixe (api, v1, v2 usw.) werden entfernt.
| Endpunkt | Generierter Name | Hinweise |
|---|---|---|
| GET /users | users_get | Die Methode wird zum Suffix |
| POST /users | users_create | POST wird zu create |
| GET /users/{id} | users_by_id_get | Pfadparameter werden zu by_{param} |
| DELETE /users | users_delete | DELETE wird zu delete |
| GET /api/v1/users | users_get | Das Präfix /api/v1 wird entfernt |
Mit operationId
Ist eine operationId definiert, hat sie Vorrang. CamelCase wird in snake_case umgewandelt und das Aktionsverb für einheitliches Wildcard-Matching ans Ende verschoben.
| operationId | Generierter Name | Hinweise |
|---|---|---|
| getUsers | users_get | CamelCase wird umgewandelt und das Verb zum Suffix verschoben |
| createUser | user_create | Das vorangestellte Verb wird neu positioniert |
| user_profile | user_profile_get | Kein Verb erkannt; Methodensuffix wird ergänzt |
| Methode | Verb-Suffix |
|---|---|
| GET | _get |
| POST | _create |
| PUT | _update |
| PATCH | _patch |
| DELETE | _delete |
Diese Namenskonvention ermöglicht die Gruppierung per Wildcard. So entspricht api:my_api.users_* beispielsweise allen benutzerbezogenen Endpunkten unabhängig von ihrer HTTP-Methode; api:my_api.*_get entspricht allen schreibgeschützten Endpunkten.
Tools im Agent YAML referenzieren
Referenziere API Spec Tools für den Agenten in dessen Liste tools. Verwende dazu das Präfix api:, gefolgt vom Namen der Spezifikation und des Tools. Mit Wildcards lassen sich Gruppen von Tools einbinden, ohne jedes einzeln aufzulisten.
tools:
- api:my_api.* # All tools from this spec
- api:my_api.users_* # All user-related tools
- api:my_api.users_get # One specific toolAPI-Spec-Tool-Referenzen lassen sich mit anderen Tool-Typen kombinieren, etwa mit vordefinierten Tools, Database Tools und Retrieval Tools – alle in derselben Liste tools.
Tools verwalten
Konfiguriere jede importierte Operation über ihre Tool-Liste.
Schalte einzelne Tools ein oder aus. Deaktivierte Tools werden von Wildcard-Matches ausgeschlossen und können von Agenten nicht aufgerufen werden – selbst bei expliziter Referenz.
Passe Namen oder Beschreibung jedes Tools an. Beim Aktualisieren bleiben eigene Namen und Beschreibungen für Endpunkte erhalten, die anhand von HTTP-Methode und Pfad zugeordnet werden.
Beim Aktualisieren wird die Quell-URL erneut abgerufen. Die gefundenen Endpunkte bestimmen die Menge der Tools; bei übereinstimmenden Endpunkten bleiben eigene Namen, Beschreibungen und Aktivierungsstatus erhalten.
Authentifizierungstypen
Konfiguriere die Authentifizierung beim Hinzufügen oder Bearbeiten eines API Spec Tools. Zugangsdaten werden sicher gespeichert und in jede Anfrage eingefügt, die der Agent an die Ziel-API stellt.
| Typ | Konfiguration | Gesendeter Header |
|---|---|---|
| Bearer Token | Token-Wert | Authorization: Bearer {token} |
| API Key | Header-Name und Key-Wert | {header}: {key} |
| Basic Auth | Benutzername und Passwort | Authorization: Basic {base64} |
Änderungen an der Konfiguration eines API Spec Tools werden wirksam, wenn die Agenten erneut bereitgestellt werden. Öffne die Seite Deployment und stelle die Agenten, die diese Spezifikation verwenden, erneut bereit.