# Agentische API ### **Umfang.** > Kundenorientiertes Onboarding für die Blockbrain Agentic API: was sie ist, wie man sich authentifiziert, wie man den ersten Aufruf macht, vier End-to-End-Use-Cases und ein Fehlercode-Katalog. > > **Die Referenz pro Endpoint wird hier absichtlich nicht dupliziert.** Die Live-Referenz, die stets aktuell ist, befindet sich unter [agentic.theblockbrain.ai/docs](https://agentic.theblockbrain.ai/docs) (Scalar, automatisch aus der OpenAPI-Spezifikation gerendert). Diese Seite behandelt das, was Scalar nicht automatisch erzeugen kann — Beschreibung, Auth-Flow und End-to-End-Use-Cases. > > **Live-OpenAPI-Spezifikation:** [`agentic.theblockbrain.ai/openapi.json`](https://agentic.theblockbrain.ai/openapi.json) (derzeit Version `0.97.2`). *** ### Überblick Die Blockbrain Agentic API stellt die Agentenplattform von Blockbrain bereit — Chat-Threads, Streaming-Antworten von Agenten, Workflows, geplante Nachrichten, benutzerdefinierte Supervisoren und Konversationsspeicher — als REST API, geschützt durch Bearer-JWT-Authentifizierung. **Basis-URL:** `https://agentic.theblockbrain.ai` Die Endpunkte sind in neun logische Gruppen organisiert. Verwenden Sie diese Tabelle, um die richtige Gruppe zu finden; Details zu jedem Endpunkt stehen in [Scalar](https://agentic.theblockbrain.ai/docs). | Gruppe | Wofür es gedacht ist | Häufig verwendeter Start-Endpunkt | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | **DynamicChat** *(v2, empfohlen)* | Chat-Produkt mit Agent im Zentrum. Thread erstellen, Nachricht senden, Antwort des Agenten streamen. Verwenden Sie dies für neue Chat-Integrationen. | `POST /v2/api/threads` | | **Agents** | Verfügbare Agenten und ihre Tools, Folgefragen sowie den niedrigeren Streaming-Endpunkt auflisten, der DynamicChat antreibt. | `GET /v1/api/agents` | | **Speicher** *(v1)* | Niedrigere Speicherschicht, auf der Agent-Threads aufbauen — Nachrichtenverlauf, Arbeitsgedächtnis, Tracking der Token-Nutzung, Massenexport/-löschung. | `GET /v1/api/memory/threads/{threadId}/messages` | | **Workflows** | Agentic Workflows synchron oder asynchron ausführen, den Status abfragen, Ergebnisse abrufen oder Ereignisse in einen laufenden Workflow senden. | `POST /v1/api/agentic/workflows/run` | | **Geplante Nachrichten** | Wiederkehrende geplante Nachrichten erstellen, auflisten, umschalten und löschen, die in einem festen Rhythmus in einen Thread ausgelöst werden. | `POST /v1/api/scheduled-messages` | | **Benutzerdefinierte Supervisoren** | Einen Multi-Agenten-Supervisor über eine kuratierte Menge von Sub-Agenten aufbauen. CRUD für Supervisor-Konfigurationen + Auflistung der zulässigen Sub-Agenten. | `GET /v1/api/supervisors/available-agents` | | **Benutzerdefinierte Agenten** | Einen in der Blockbrain-UI erstellten benutzerdefinierten Agenten als GitHub-Issue exportieren (verwendet zur Überführung in einen vordefinierten Agenten). | `POST /v1/api/custom-agents/{customAgentId}/export` | | **Modelle** | Die von der Plattform bereitgestellten Modelle mit Anzeigemetadaten auflisten. Nützlich für Model-Picker. | `GET /v1/api/models` | | **System** | Health Check, strukturierter Changelog, [llms.txt](https://llmstxt.org/) für die Entdeckung durch KI-Tools, Scalar-Dokumentations-UI. | `GET /healthz` | > **Memory v1 vs. DynamicChat v2 — welche Threads verwende ich?** Das sind zwei unterschiedliche Systeme. Neue Chat-Integrationen sollten die v2-DynamicChat-Thread-Oberfläche verwenden (`/v2/api/threads`). Die Memory-v1-Oberfläche (`/v1/api/memory/threads`) ist die Speicherschicht, aus der ältere v1-Agenten lesen; normalerweise rufen Sie sie direkt nur auf, wenn Sie Daten migrieren oder eine UI für Speicherverwaltung erstellen. *** ### Authentifizierung Jeder geschützte Endpunkt erwartet ein Bearer-JWT im `Authorization` -Header: ``` Authorization: Bearer ``` Das JWT wird vom Identitätsanbieter von Blockbrain unter `auth.theblockbrain.ai`ausgestellt. Die Agentic API validiert die Signatur des Tokens gegen die öffentlichen JWKs unter: ``` https://auth.theblockbrain.ai/oauth/v2/keys ``` …und erzwingt dann den Audience-Claim, das Ablaufdatum und den Signaturalgorithmus (`RS256`). #### Erwartete Token-Claims ```json { "sub": "user_12345", "external_user_id": "ext_abc", "urn:zitadel:iam:org:id": "tenant_xyz", "urn:zitadel:iam:org:project:roles": { "kb:consumer": { "projectId": "domain" } }, "iat": 1700000000, "exp": 1700003600, "aud": ["agentic-api-audience"] } ``` Die Agentic API leitet den aufrufenden Benutzer aus `sub`ab, den Mandanten aus `urn:zitadel:iam:org:id`und (falls vorhanden) die kundenseitige Kennung aus `external_user_id`. #### Token beziehen Für einen **internen Blockbrain-Benutzer**stammt das JWT aus dem vorhandenen Login-Flow (Web-App, Mobile usw.) und kann aus der aktiven Browsersitzung übernommen werden. Für einen **externen Kundenintegration**wird Ihr Blockbrain-Kundenteam eine der folgenden Optionen bereitstellen: 1. **OAuth-2.0-Client-Credentials** gegen `auth.theblockbrain.ai` (`POST /oauth/v2/token` mit `grant_type=client_credentials`, eine vom Mandanten ausgegebene `client_id` / `client_secret`). Geeignet für Service-zu-Service-Szenarien. 2. **Ein vom Mandanten ausgegebenes, langlebiges API-Token** von Ihrem Blockbrain-Mandantenadministrator erstellt und als Bearer-JWT verwendet. Wenden Sie sich an Ihren Customer Success Manager für die Zugangsdaten und den zu verwendenden Wert des Audience-Claims. *** ### Erste Schritte #### Voraussetzungen * Ein Bearer-JWT. * Ein HTTP-Client mit HTTPS-Unterstützung (`curl`, `httpx`, `fetch` usw.). #### Verfügbare Agenten auflisten Bestätigen Sie, dass die Authentifizierung funktioniert, und finden Sie heraus, welche Agenten Ihr Mandant bereitstellt: ```shell curl -s https://agentic.theblockbrain.ai/v1/api/agents \ -H "Authorization: Bearer $TOKEN" \ | jq ``` Gibt eine Liste von Agenten mit ihren `id`-, Anzeige-Metadaten und Fähigkeiten zurück. Wählen Sie einen `agentId` für den nächsten Schritt. #### Einen Chat-Thread erstellen (DynamicChat v2) ```shell curl -s -X POST https://agentic.theblockbrain.ai/v2/api/threads \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "agentId": "", "title": "My first thread" }' \ | jq ``` `agentId` ist eine Workspace-Agent-UUID (weglassen, um auf einen Standardwert zurückzufallen). Gibt ein Thread-Objekt mit `threadId`. #### Nachricht senden und die Antwort streamen ```shell curl -N -X POST "https://agentic.theblockbrain.ai/v2/api/threads/$THREAD_ID/messages" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "parts": [{ "type": "text", "text": "Hello!" }] } ] }' ``` #### Thread-Verlauf abrufen ```shell curl -s "https://agentic.theblockbrain.ai/v2/api/threads/$THREAD_ID/messages" \ -H "Authorization: Bearer $TOKEN" \ | jq ``` Gibt die letzten 50 Nachrichten als AI SDK v6 UIMessages zurück. *** ### Shortcut für KI-Tools: `llms.txt` Die Agentic API veröffentlicht eine maschinenlesbare Zusammenfassung aller öffentlichen Endpunkte unter: ``` https://agentic.theblockbrain.ai/llms.txt ``` Dies folgt der [llmstxt.org](https://llmstxt.org/) Konvention — verweisen Sie Ihren KI-Coding-Assistenten oder MCP-Client auf diese URL, und er kann Endpunkte selbst entdecken, ohne das vollständige OpenAPI-Dokument zu parsen. *** ### Anwendungsfälle End-to-End-Abläufe für die vier am häufigsten nachgefragten Kundenszenarien. Jeder ist kombinierbar — Sie können sie in Ihrer Anwendung miteinander verbinden. #### Ein Chatbot-Frontend bauen (DynamicChat v2) **Ziel:** eine Chat-UI, in der ein Benutzer einen Thread auswählt, eine Nachricht eingibt und zusieht, wie der Agent eine Antwort streamt. | Schritt | Endpunkt | Zweck | | ------- | ------------------------------------------ | --------------------------------------------------------------------------------------- | | 1 | `GET /v2/api/threads` | Die Threads des aktuellen Benutzers beim ersten Laden auflisten. | | 2 | `POST /v2/api/threads` | Einen neuen Thread erstellen, wenn der Benutzer auf *Neuer Chat*. | | 3 | `GET /v2/api/threads/{threadId}/messages` | Die Nachrichtenhistorie laden, wenn ein Thread geöffnet wird. | | 4 | `POST /v2/api/threads/{threadId}/messages` | Die Eingabe des Benutzers senden und die Antwort des Agenten streamen (SSE). | | 5 | `POST /v2/api/threads/{threadId}/agent` | (Optional) Den dem Thread zugeordneten Agenten wechseln, ohne den Verlauf zu verlieren. | | 6 | `DELETE /v2/api/threads/{threadId}` | Einen Thread aus dem Verlauf des Benutzers entfernen. | | 7 | `GET /v1/api/agents/follow-up/{threadId}` | Vorgeschlagene Folgefragen abrufen, um sie unter der neuesten Antwort anzuzeigen. | #### Einen agentic Workflow asynchron ausführen **Ziel:** einen lang laufenden Workflow starten, den Fortschritt abfragen, Ergebnisse abrufen. | Schritt | Endpunkt | Zweck | | ------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `GET /v1/api/agentic/workflows/get-workflows` | Die Workflows entdecken, die der aufrufende Benutzer ausführen kann. | | 2 | `POST /v1/api/agentic/workflows/run` | Einen asynchronen Lauf starten. Gibt eine `artificialRunId`. | | 3 | `GET /v1/api/agentic/workflows/get-status/run-id/{artificialRunId}/last-id/{lastId}` | Auf inkrementelle Status-Updates pollen. Übergeben Sie das vorherige `lastId` bei jedem Aufruf, um dort fortzufahren, wo Sie aufgehört haben. | | 4 | `POST /v1/api/workflows/send-event` | (Optional) Ein Ereignis in den laufenden Workflow senden — für Human-in-the-Loop- oder Verzweigungslogik. | | 5 | `GET /v1/api/agentic/workflows/get-results/workflow/{workflowId}` | Sobald der Status die Fertigstellung meldet, das strukturierte Ergebnis abrufen. | > **Für kurze, blockierende Aufrufe:** verwenden Sie `POST /v1/api/run-workflow` stattdessen — es wird synchron ausgeführt und liefert das Ergebnis in einem einzigen Roundtrip zurück. #### Eine wiederkehrende Agentennachricht planen **Ziel:** einen Agenten automatisieren, der nach einem festen Zeitplan in einen Thread schreibt (z. B. *"jeden Werktag um 09:00 die offenen Probleme von gestern zusammenfassen"*). | Schritt | Endpunkt | Zweck | | ------- | --------------------------------------------- | ------------------------------------------------------------------------------- | | 1 | `POST /v1/api/scheduled-messages` | Den Zeitplan erstellen (Ziel-Thread, Cron-Ausdruck, Nachrichten-Payload). | | 2 | `GET /v1/api/scheduled-messages` | Vorhandene Zeitpläne für den Benutzer auflisten (oder filtern nach `threadId`). | | 3 | `PUT /v1/api/scheduled-messages/{id}` | Rhythmus oder Payload bearbeiten. | | 4 | `POST /v1/api/scheduled-messages/{id}/toggle` | Anhalten oder fortsetzen, ohne die Konfiguration zu verlieren. | | 5 | `DELETE /v1/api/scheduled-messages/{id}` | Dauerhaft entfernen. | #### Einen benutzerdefinierten Supervisor über kuratierte Sub-Agenten aufbauen **Ziel:** mehrere bestehende Agenten unter einem einzigen Supervisor-Agenten zusammenfassen, der intelligent delegiert. | Schritt | Endpunkt | Zweck | | ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- | | 1 | `GET /v1/api/supervisors/available-agents` | Agenten-IDs auflisten, die als Sub-Agenten geeignet sind. | | 2 | `POST /v1/api/supervisors` | Die Supervisor-Konfiguration mit den ausgewählten Sub-Agenten und Routing-Regeln erstellen. | | 3 | `GET /v1/api/supervisors` | Supervisoren in der Organisation für die Verwaltungs-UI auflisten. | | 4 | `PUT /v1/api/supervisors/{id}` | Das Set der Sub-Agenten oder das Routing an sich ändernde Anforderungen anpassen. | | 5 | `DELETE /v1/api/supervisors/{id}` | Entfernen. | Nach der Erstellung erscheint der Supervisor in der Standard- `GET /v1/api/agents` Auflistung und kann über jeden der oben genannten Chat-Flows verwendet werden. *** ### Fehlercode-Katalog Jeder Endpunkt folgt den unten stehenden Standard-HTTP-Status-Konventionen. Endpunktspezifische Bodies (z. B. *"Thread nicht gefunden oder nicht dem Aufrufer gehörend"* bei `404`) sind dokumentiert in [Scalar](https://agentic.theblockbrain.ai/docs). | Status | Bedeutung | Was zu tun ist | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **200** | Erfolg — der Body enthält die Ressource oder den Stream. | Fortfahren. | | **201** | Erstellt — wird typischerweise von `POST`s zurückgegeben, die eine neue Entität erstellen. | Lesen Sie das `id` aus der Antwort und fahren Sie fort. | | **204** | Erfolg, kein Body — typisch für `DELETE`. | Fortfahren. | | **400** | Fehlerhafte Anfrage — Body-Form oder Query-Parameter stimmen nicht mit dem Schema überein. | Validieren Sie den Request-Body gegen das Schema in [Scalar](https://agentic.theblockbrain.ai/docs). Häufige Ursachen: fehlendes Pflichtfeld, falscher Content-Type, ungültiges JSON. | | **401** | Nicht autorisiert — fehlendes, fehlerhaftes oder abgelaufenes Bearer-Token. | Token neu beziehen. Bestätigen Sie `Authorization: Bearer …` -Header vorhanden ist und das Token nicht abgelaufen ist (`exp` -Claim). | | **403** | Verboten — Token ist gültig, aber dem Aufrufer fehlt die Berechtigung für diese Ressource. | Prüfen Sie die Mandantenzuordnung und alle erforderlichen Rollen-Claims im JWT. | | **404** | Nicht gefunden — Ressource existiert nicht oder ist für den Aufrufer nicht sichtbar. Hinweis: Viele Endpunkte geben 404 statt 403 zurück, um das Offenlegen der Existenz zu vermeiden (z. B. *"Thread nicht gefunden oder nicht dem Aufrufer gehörend"*). | IDs prüfen. Wenn Sie Zugriff erwarten, Mandanten-/Benutzerzuordnung überprüfen. | | **409** | Konflikt — der Zustand der Ressource verhindert die Operation (z. B. doppelte Erstellung). | Client-seitigen Zustand abgleichen und erneut versuchen. | | **429** | Ratenbegrenzung erreicht. | Mit exponentieller Verzögerung zurückoffen; falls vorhanden, den `Retry-After` -Header beachten. | | **500** | Interner Fehler auf Seiten von Blockbrain. | Mit Backoff erneut versuchen. Wenn der Fehler bestehen bleibt, mit Request-ID und Zeitstempel an den Support weitergeben. | | **503** | Dienst vorübergehend nicht verfügbar. | Erneut versuchen; falls länger anhaltend, prüfen Sie `/healthz` und die Statusseite der Plattform. | *** ### Format der Streaming-Antwort Es gibt zwei Streaming-Endpunkte — verwenden Sie für neue Integrationen den v2-Endpunkt (aktuell). | Endpunkt | Status | Format | | ------------------------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `POST /v2/api/agents/{agentId}/stream` | **Aktuell** | AI SDK v6 **UIMessage** SSE-Stream. Jeder Chunk ist ein SSE- `data:` Ereignis, dessen Payload ein UIMessage-Delta ist. | | `POST /v2/api/threads/{threadId}/messages` | **Aktuell (DynamicChat)** | Dasselbe AI SDK v6 UIMessage-SSE-Format. Der Thread-Kontext wird aus dem Pfad übernommen; die Benutzeridentität aus dem JWT. | | `POST /v1/api/agents/{agentId}/stream` | **Veraltet** | SSE mit benannten Ereignissen (`event: ` / `data: `). Nicht für neue Integrationen verwenden. | | `POST /api/agents/{agentId}/stream` | **Legacy AI SDK v1** | Älteres `data:` Chunk-Format. Nur zur Rückwärtskompatibilität gepflegt. | **Tipp zum Umgang mit SSE.** Verwenden Sie einen Streaming-HTTP-Client (`fetch` mit einem `ReadableStream` Reader, `httpx` asynchronem Streaming oder der `eventsource` Node-Bibliothek) und parsen Sie vollständige SSE-Event-Blöcke statt zeilenweise zu puffern. UIMessage-Deltas sind JSON; verketten Sie die `text` -Teile beim Eintreffen, um inkrementelle Ausgabe darzustellen. *** ### Servicezustand und Erkennung | Endpunkt | Zweck | | ---------------- | -------------------------------------------------------------------------------------- | | `GET /healthz` | Liveness-Probe. Gibt 200 zurück, wenn der Dienst gesund ist. Gut zum Caching geeignet. | | `GET /changelog` | Strukturierte Release Notes für den Agentic-Service. | | `GET /llms.txt` | Maschinenlesbare Zusammenfassung der Endpunkte. | | `GET /docs` | Die interaktive Scalar-Referenz. | *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.blockbrain.ai/de/fur-administratoren/agentische-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.