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 (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 (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.

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 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 <jwt>

Das JWT wird vom Identitätsanbieter von Blockbrain unter auth.theblockbrain.aiausgestellt. 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

{
  "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 subab, den Mandanten aus urn:zitadel:iam:org:idund (falls vorhanden) die kundenseitige Kennung aus external_user_id.

Token beziehen

Für einen internen Blockbrain-Benutzerstammt das JWT aus dem vorhandenen Login-Flow (Web-App, Mobile usw.) und kann aus der aktiven Browsersitzung übernommen werden.

Für einen externen Kundenintegrationwird 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:

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)

curl -s -X POST https://agentic.theblockbrain.ai/v2/api/threads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "agentId": "<AGENT_UUID>",
        "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

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

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 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.

Status	Bedeutung	Was zu tun ist
200	Erfolg — der Body enthält die Ressource oder den Stream.	Fortfahren.
201	Erstellt — wird typischerweise von POSTs 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. 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: <type> / data: <json>). 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.

---