REST-API-Referenz

Interaktive Dokumentation

Jede Agent-Lab-Anwendung stellt automatisch OpenAPI 3 bereit – die Referenzimplementierung unter http://localhost:18000/docs (bzw. Ihre eigene Anwendung, wo immer sie läuft). Der folgende Katalog dokumentiert die integrierten Router des Frameworks; Ihre extra_routers erscheinen im selben Schema.

Authentifizierung

Wenn auth.enabled auf true steht (siehe die Konfigurationsreferenz), erfordern die Routen ein Keycloak-Bearer-Token. Der /auth-Router wird nur eingebunden, wenn die Authentifizierung aktiviert ist:

TOKEN=$(curl -s -X POST https://<host>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "…", "password": "…"}' | jq -r '.access_token')

curl -s https://<host>/agents/list -H "Authorization: Bearer $TOKEN" | jq

Die Einrichtung von Realm und Client wird unter Authentifizierung mit Keycloak beschrieben.

Pfade ohne Authentifizierung: /status/*, /docs, /openapi.json, /mcp, /static, die OAuth-Well-Known-Endpoints und der SPA-Mount – alles andere erfordert ein gültiges Token.

Endpoints

Agenten

Erstellen Sie Instanzen jedes registrierten Agententyps; agent_type wird dynamisch gegen die Registry validiert.

Nachrichten

Sprachmodelle

Integrationen

Anhänge

Status und MCP

Request-Beispiele

Eine Agent-Instanz erstellen – agent_name akzeptiert [a-zA-Z0-9_-]; agent_type muss ein registrierter Typ sein; language_model_id ist optional:

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{
        "agent_name": "support-agent-1",
        "agent_type": "coordinator_planner_supervisor",
        "language_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }' | jq

Eine Nachricht senden – message_role ist einer der Werte human, assistant, tool; attachment_id ist optional:

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message_role": "human",
        "message_content": "Summarize the attached report.",
        "attachment_id": null
      }' | jq

Eine Agent-Einstellung aktualisieren – setting_key akzeptiert [a-zA-Z_-]; setting_value fasst bis zu 16.000 Zeichen (hier liegen Prompt-Templates und JSON-Payloads – siehe das Entity-Domänenmodell):

curl -s -X POST http://localhost:18000/agents/update_setting \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "setting_key": "system_prompt",
        "setting_value": "You are a concise research assistant…"
      }' | jq

Konventionen

• IDs sind UUIDs; alle List-Endpoints akzeptieren JSON-Bodys, keine Query-Strings.
• Einstellungen sind Key-Value-Paare, die mit dem Agenten oder Modell persistiert werden – so betreibt dieselbe Implementierung viele unterschiedlich konfigurierte Instanzen.
• Die Registry ist die maßgebliche Quelle für gültige agent_type-Werte – rufen Sie GET /agents/types auf, um zu sehen, was die laufende Anwendung entdeckt hat (einschließlich Ihrer eigenen Pakete über scan_packages).