Agent-Test-API (Aktualisieren/Veröffentlichen)
Agent-Test-API (Aktualisieren/Veröffentlichen)
Ermöglicht Entwickler:innen, in KI-Tools wie CodeX, Claude usw. (mit installierter GPTBots Agent Skill) die von den Skills erzeugte .bot-Dateikonfiguration in einen Ziel-Agent der GPTBots-Plattform zu importieren und zu veröffentlichen.
⚠️ Nur Agents im „Testmodus" können aufgerufen werden. Ein Aufruf im Produktivmodus gibt
403200zurück. Der Testmodus wird beim Erstellen des Agents ausgewählt und kann nach der Erstellung nicht mehr geändert werden.
Agent-Aktualisierungs-API (Import einer .bot-Datei zum Ersetzen der aktuellen Version)
Importiert die .bot-Datei in den Ziel-Agent (Testmodus) und speichert die ersetzte aktuelle Konfiguration als eine neue Entwurfsversion (die zugleich zur „aktuellen Version" wird). Es gelten folgende Regeln:
- Wissensdatenbank (Datengruppe) / Datenbanktabellen / Wissensdokumente: nach Dimension AgentID; gehören sie weiterhin zum Ziel-Agent, werden sie beibehalten, andernfalls verworfen;
- Verknüpfte Workflows / Tools (Plugins): nach Dimension Organisation; sind sie weiterhin gültig, werden sie beibehalten, andernfalls verworfen;
- Auf oberster Ebene eingebundene Wissensdatenbanken werden nicht mit der
.bot-Datei exportiert; beim Import werden die vom Ziel-Agent selbst eingebundenen Wissensdatenbanken beibehalten; - Anmeldedaten von Drittanbietern: Beim Import in einen bestehenden Agent werden die bereits am Ziel konfigurierten Anmeldedaten anhand „identischer Komponenten-/Knoten-/Plugin-ID" zurückgeschrieben; bereits authentifizierte Komponenten werden nicht geleert, um die Nutzbarkeit sicherzustellen;
Anfragemethode
POST
Anfrage-URL
https://api-${endpoint}.gptbots.ai/v1/agent/version/import
Anfrage
Beispielanfrage
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/import' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@my-agent.bot' \
-F 'versionDesc=Imported by AI tool'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/import' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@my-agent.bot' \
-F 'versionDesc=Imported by AI tool'
Dieser Codeblock im schwebenden Fenster
Anfrage-Header
| Feld | Typ | Beschreibung |
|---|---|---|
| Authorization | Bearer {API Key} | Verwenden Sie Authorization: Bearer {API Key} für die Authentifizierung. Den Schlüssel erhalten Sie im Kanal „Integration / API" des Ziel-Agents als API Key. |
| Content-Type | multipart/form-data | Datentyp, auf multipart/form-data setzen. |
Anfrageparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| file | file | Ja | Binäre .bot-Datei. |
| versionDesc | text | Nein | Versionsbeschreibung. |
Die Versionsnummer wird serverseitig automatisch generiert (letzter Abschnitt der neuesten Version +1; ohne vorhandene Historie ist sie
1.0.0).
Antwort
Beispielantwort
{
"code": 0,
"msg": "OK",
"data": {
"botId": "xxx",
"botType": "QuestionAnswer",
"version": "1.0.3"
}
}
{
"code": 0,
"msg": "OK",
"data": {
"botId": "xxx",
"botType": "QuestionAnswer",
"version": "1.0.3"
}
}
Dieser Codeblock im schwebenden Fenster
Erfolgsantwort
| Feld | Typ | Beschreibung |
|---|---|---|
| botId | string | ID des Ziel-Agents. |
| botType | string | Agent-Typ (QuestionAnswer / Flow / LoopAgent). |
| version | string | Die in diesem Vorgang gespeicherte Versionsnummer (d. h. die aktuelle Version). |
Fehlerantwort
| Feld | Typ | Beschreibung |
|---|---|---|
| code | int | Fehlercode. |
| msg | string | Fehlerdetails. |
Agent-Veröffentlichungs-API (Veröffentlichung einer Versionsnummer als Online-Version)
Veröffentlicht die angegebene Versionsnummer des Ziel-Agents (Testmodus) als produktive Online-Version (diese Version wird „online", die übrigen Versionen kehren in den Entwurfsstatus zurück).
Anfragemethode
POST
Anfrage-URL
https://api-${endpoint}.gptbots.ai/v1/agent/version/release
Anfrage
Beispielanfrage
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/release' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"version": "1.0.3"
}'
curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/version/release' \
-H 'Authorization: Bearer {AGENT_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"version": "1.0.3"
}'
Dieser Codeblock im schwebenden Fenster
Anfrage-Header
| Feld | Typ | Beschreibung |
|---|---|---|
| Authorization | Bearer {API Key} | Verwenden Sie Authorization: Bearer {API Key} für die Authentifizierung. Den Schlüssel erhalten Sie im Kanal „Integration / API" des Ziel-Agents als API Key. |
| Content-Type | application/json | Datentyp, auf application/json setzen. |
Anfrageparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| version | string | Ja | Die als online zu veröffentlichende Versionsnummer (z. B. 1.0.3); üblicherweise die von der „Aktualisierungs"-Schnittstelle zurückgegebene version. |
Antwort
Beispielantwort
{
"code": 0,
"msg": "OK"
}
{
"code": 0,
"msg": "OK"
}
Dieser Codeblock im schwebenden Fenster
Erfolgsantwort
Kein Datenkörper; code gleich 0 bedeutet erfolgreiche Veröffentlichung.
Fehlerantwort
| Feld | Typ | Beschreibung |
|---|---|---|
| code | int | Fehlercode. |
| msg | string | Fehlerdetails. |
Fehlercodes
Die Aktualisierungs- und die Veröffentlichungs-Schnittstelle teilen sich denselben Satz an Fehlercodes:
| Code | Message |
|---|---|
| 0 | Erfolg |
| 20055 | Der API-Kanal dieses Agents ist nicht aktiviert. Aktivieren Sie zuerst den API-Schalter unter „Integration / API“ |
| 40000 | Ungültiger Parameter. Die Veröffentlichungs-API wurde ohne version aufgerufen; oder die Loop-Control-Werte des importierten LoopAgent sind ungültig (maxTurns muss zwischen 1 und 100 liegen, maxErrors zwischen 0 und 50, maxBudgetInputTokens ≥ 0, und alle müssen ganze Zahlen sein) |
| 40001 | Zu viele Anfragen: Diese Schnittstelle ist auf 30 Anfragen pro Minute je Agent begrenzt |
| 40008 | Zu viele Anfragen: Das RPM-Limit des Tarifs für „sonstige APIs“ wurde überschritten (wird nicht ausgelöst, wenn der Tarif dieses Limit nicht festlegt) |
| 40101 | Der Authorization-Header ist leer |
| 40127 | Entwickler-Authentifizierung fehlgeschlagen: Ungültiger API Key |
| 40348 | Agent existiert nicht. Wird nur zurückgegeben, wenn der Agent nach der Authentifizierung gleichzeitig gelöscht wird; ein ungültiger API Key liefert 40127, ein gelöschter Agent 40378 |
| 40353 | Die Funktion ist erst nach einem Tarif-Upgrade verfügbar. Veröffentlichungs-API: Die Anzahl der Veröffentlichungen hat das Tariflimit erreicht (die Antwort enthält diese allgemeine Meldung ohne Angabe des Limits) |
| 40355 | Flow-Regel ungültig. Veröffentlichungs-API: Das Ziel ist ein Flow-Agent mit ungültigem Flussdiagramm |
| 40378 | Agent wurde gelöscht |
| 200268 | Agent/Workflow-Versionsnummer existiert bereits: Die automatisch ermittelte Versionsnummer kollidiert mit einer vorhandenen Version (der HTTP-Status dieses Codes ist 200) |
| 403200 | Nicht im Testmodus: Nur Agents im Testmodus können über diese API aktualisiert oder veröffentlicht werden |
| 403201 | Importdateityp stimmt nicht mit dem Typ des Ziel-Agents überein |
| 403202 | Analyse der importierten .bot-Datei fehlgeschlagen |
| 403203 | Angegebene Versionsnummer existiert nicht |
| 403204 | API-Key-Typ stimmt nicht mit der Schnittstelle überein: Diese Schnittstelle akzeptiert nur Agent Key |