# Agentische API ### **Umfang.** > Einführung für Kunden in 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 Endpunkt wird hier absichtlich nicht doppelt aufgeführt.** Die Live-Referenz, die immer aktuell ist, finden Sie 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 generieren 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`). *** ### Übersicht Die Blockbrain Agentic API stellt die Agentenplattform von Blockbrain bereit — Chat-Threads, gestreamte Agentenantworten, Workflows, geplante Nachrichten, benutzerdefinierte Supervisoren und Gesprächsspeicher — als REST-API, geschützt durch Bearer-JWT-Authentifizierung. **Basis-URL:** `https://agentic.theblockbrain.ai` Die Endpunkte sind in neun logische Gruppen organisiert. Nutzen Sie diese Tabelle, um die richtige Gruppe zu finden; Details zu jedem Endpunkt finden Sie in [Scalar](https://agentic.theblockbrain.ai/docs). | Gruppe | Wofür es gedacht ist | Typischer Einstiegspunkt | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | | **DynamicChat** *(v2, empfohlen)* | Agentenorientiertes Chat-Produkt. Erstellen Sie einen Thread, senden Sie eine Nachricht, streamen Sie die Antwort des Agenten. Verwenden Sie dies für neue Chat-Integrationen. | `POST /v2/api/threads` | | **Agents** | Verfügbare Agenten und ihre Tools, Anschlussfragen sowie den tieferliegenden Streaming-Endpunkt auflisten, der DynamicChat antreibt. | `GET /v1/api/agents` | | **Speicher** *(v1)* | Tieferliegender Speicher, der Agenten-Threads unterstützt — Nachrichtenverlauf, Arbeitsspeicher, Nachverfolgung der Token-Nutzung, Massenexport/-löschung. | `GET /v1/api/memory/threads/{threadId}/messages` | | **Workflows** | Agentische Workflows synchron oder asynchron ausführen, Status abfragen, Ergebnisse abrufen oder Ereignisse in einen laufenden Workflow einspeisen. | `POST /v1/api/agentic/workflows/run` | | **Geplante Nachrichten** | Wiederkehrende geplante Nachrichten erstellen, auflisten, aktivieren/deaktivieren und löschen, die in einem festen Rhythmus in einen Thread gesendet werden. | `POST /v1/api/scheduled-messages` | | **Benutzerdefinierte Supervisoren** | Einen Multi-Agent-Supervisor über eine kuratierte Menge von Unteragenten erstellen. CRUD für Supervisor-Konfigurationen + Auflistung der zulässigen Unteragenten. | `GET /v1/api/supervisors/available-agents` | | **Benutzerdefinierte Agenten** | Einen in der Blockbrain-UI erstellten benutzerdefinierten Agenten als GitHub-Issue exportieren (wird für die Überführung in einen vordefinierten Agenten verwendet). | `POST /v1/api/custom-agents/{customAgentId}/export` | | **Modelle** | Die von der Plattform bereitgestellten Modelle mit Anzeige-Metadaten auflisten. Nützlich zum Erstellen von Modell-Auswahlen. | `GET /v1/api/models` | | **System** | Health-Check, strukturiertes Änderungsprotokoll, [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?** Es 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 Speicher-Ebene, 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 anhand der öffentlichen JWKs unter: ``` https://auth.theblockbrain.ai/oauth/v2/keys ``` …und erzwingt anschließend 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 bestehenden Login-Flow (Web-App, Mobilgerät usw.) und kann aus der aktiven Browser-Sitzung übernommen werden. Für einen **externen Kundenintegration**stellt Ihr Blockbrain-Account-Team eines der folgenden Dinge bereit: 1. **OAuth 2.0 Client Credentials** gegen `auth.theblockbrain.ai` (`POST /oauth/v2/token` mit `grant_type=client_credentials`, eine vom Mandanten ausgestellte `client_id` / `client_secret`). Geeignet für Service-zu-Service-Szenarien. 2. **Ein vom Mandanten ausgestelltes langlebiges API-Token** von Ihrem Blockbrain-Mandantenadministrator erstellt und als Bearer-JWT verwendet. Wenden Sie sich an Ihren Customer Success Manager, um die Zugangsdaten und den zu verwendenden Audience-Claim-Wert zu erhalten. *** ### 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 für den nächsten Schritt eine `agentId` aus. #### 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": "Mein erster Thread" }' \ | jq ``` `agentId` ist eine UUID eines Workspace-Agenten (weglassen, um auf einen Standardwert zurückzufallen). Gibt ein Thread-Objekt mit `threadId`. #### Nachricht senden und 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": "Hallo!" }] } ] }' ``` Die Antwort ist `text/event-stream` (SSE) im **AI SDK v6 UIMessage** Chunk-Format — siehe [Abschnitt 7](https://claude.ai/local_sessions/local_302fe9f7-f8af-4084-9842-6cca0d1132f5#7-streaming-response-format). #### 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. Sie haben jetzt eine funktionierende End-to-End-Schleife — erweitern Sie von hier aus mithilfe der Use Cases in [Abschnitt 5](https://claude.ai/local_sessions/local_302fe9f7-f8af-4084-9842-6cca0d1132f5#5-use-cases). *** ### Abkürzung für KI-Tools: `llms.txt` Die Agentic API veröffentlicht eine maschinenlesbare Zusammenfassung jedes öffentlichen Endpunkts 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. *** ### Use Cases End-to-End-Abläufe für die vier am häufigsten nachgefragten Kundenszenarien. Jedes ist kombinierbar — Sie können sie in Ihrer Anwendung miteinander verknüpfen. #### Ein Frontend für einen Chatbot erstellen (DynamicChat v2) **Ziel:** eine Chat-UI, in der ein Benutzer einen Thread auswählt, eine Nachricht eingibt und beobachtet, wie der Agent eine Antwort streamt. | Schritt | Endpunkt | Zweck | | ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------ | | 1 | `GET /v2/api/threads` | Beim ersten Laden die Threads des aktuellen Benutzers auflisten. | | 2 | `POST /v2/api/threads` | Einen neuen Thread erstellen, wenn der Benutzer auf *Neuer Chat*. | | 3 | `GET /v2/api/threads/{threadId}/messages` | Den Nachrichtenverlauf beim Öffnen eines Threads laden. | | 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 mit dem Thread verbundenen 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 Anschlussfragen abrufen, die unter der neuesten Antwort angezeigt werden. | #### Einen agentischen Workflow asynchron ausführen **Ziel:** einen lang laufenden Workflow starten, Fortschritt abfragen, Ergebnisse abrufen. | Schritt | Endpunkt | Zweck | | ------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `GET /v1/api/agentic/workflows/get-workflows` | Die Workflows ermitteln, 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 Statusaktualisierungen pollen. Übergeben Sie die 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 den Abschluss meldet, das strukturierte Ergebnis abrufen. | > **Für kurze, blockierende Aufrufe:** verwendet `POST /v1/api/run-workflow` stattdessen — es wird synchron ausgeführt und gibt das Ergebnis in einem einzigen Roundtrip zurück. #### Eine wiederkehrende Agentennachricht planen **Ziel:** einen Agenten automatisieren, der in einem festen Rhythmus in einen Thread schreibt (z. B. *„jeden Werktag um 09:00 die offenen Issues 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` | Pausieren oder fortsetzen, ohne die Konfiguration zu verlieren. | | 5 | `DELETE /v1/api/scheduled-messages/{id}` | Dauerhaft entfernen. | #### Einen benutzerdefinierten Supervisor über kuratierte Unteragenten erstellen **Ziel:** mehrere vorhandene Agenten unter einem einzigen Supervisor-Agenten bündeln, der intelligent delegiert. | Schritt | Endpunkt | Zweck | | ------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | | 1 | `GET /v1/api/supervisors/available-agents` | Agenten-IDs auflisten, die als Unteragenten geeignet sind. | | 2 | `POST /v1/api/supervisors` | Die Supervisor-Konfiguration mit den gewählten Unteragenten 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}` | Den Satz der Unteragenten oder das Routing anpassen, wenn sich die Anforderungen ändern. | | 5 | `DELETE /v1/api/supervisors/{id}` | Abbauen. | Nach der Erstellung erscheint der Supervisor in der Standard- `GET /v1/api/agents` Auflistung und ist über jeden der oben genannten Chat-Workflows nutzbar. *** ### Fehlercode-Katalog Jeder Endpunkt folgt den untenstehenden Standard-HTTP-Statuskonventionen. Endpunktspezifische Bodies (z. B. *"Thread nicht gefunden oder nicht vom Aufrufer besessen"* 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 — typischerweise zurückgegeben von `POST`s, die eine neue Entität erstellen. | Lesen Sie die `id` aus der Antwort und fahren Sie fort. | | **204** | Erfolg, kein Body — typisch für `DELETE`. | Fortfahren. | | **400** | Ungültige Anfrage — Body-Struktur oder Query-Parameter stimmen nicht mit dem Schema überein. | Validieren Sie den Request-Body anhand des Schemas in [Scalar](https://agentic.theblockbrain.ai/docs). Häufige Ursachen: fehlendes erforderliches Feld, falscher Content-Type, ungültiges JSON. | | **401** | Nicht autorisiert — fehlendes, fehlerhaftes oder abgelaufenes Bearer-Token. | Token erneut beziehen (siehe [Abschnitt 2](https://claude.ai/local_sessions/local_302fe9f7-f8af-4084-9842-6cca0d1132f5#2-authentication)). Bestätigen Sie, dass der `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. | Mandanten-Scope und alle erforderlichen Rollen-Claims im JWT überprüfen. | | **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 vom Aufrufer besessen"*). | IDs überprüfen. Wenn Sie Zugriff erwarten, Mandanten-/Benutzerscope prüfen. | | **409** | Konflikt — der Ressourcenstatus verhindert die Operation (z. B. doppelte Erstellung). | Client-seitigen Zustand abgleichen und erneut versuchen. | | **429** | Rate-Limit erreicht. | Mit exponentiellem Backoff warten; den `Retry-After` Header beachten, falls vorhanden. | | **500** | Interner Fehler auf Seiten von Blockbrain. | Mit Backoff erneut versuchen. Falls das Problem fortbesteht, mit Request-ID und Zeitstempel an den Support weiterleiten. | | **503** | Dienst vorübergehend nicht verfügbar. | Erneut versuchen; falls länger andauernd, prüfen `/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 genommen; 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 für Rückwärtskompatibilität gepflegt. | **Tipp zur SSE-Verarbeitung.** Verwenden Sie einen Streaming-HTTP-Client (`fetch` mit einem `ReadableStream` -Reader, `httpx` asynchrones Streaming oder der `eventsource` Node-Bibliothek) und parsen Sie vollständige SSE-Ereignisblöcke statt zeilenweise zu puffern. UIMessage-Deltas sind JSON; verketten Sie die `Text` -Teile, sobald sie eintreffen, um inkrementelle Ausgabe darzustellen. *** ### Systemzustand und Ermittlung | Endpunkt | Zweck | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET /healthz` | Liveness-Probe. Gibt 200 zurück, wenn der Dienst gesund ist. Cache-freundlich. | | `GET /changelog` | Strukturierte Release Notes für den Agentic-Dienst. | | `GET /llms.txt` | Maschinenlesbare Endpunktzusammenfassung (siehe [Abschnitt 4](https://claude.ai/local_sessions/local_302fe9f7-f8af-4084-9842-6cca0d1132f5#4-ai-tooling-shortcut-llmstxt)). | | `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.en.theblockbrain.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.