Sessions

Eine Session (Sitzung) ist ein Gespräch und ein Arbeitsstrang. Du gibst ihr Arbeit in Turns (Durchgängen). Ein Turn ist eine Anfrage und die ganze Arbeit des Agents, die danach folgt. Jede Session gehört zu einem Agent. Diese Seite zeigt die Routen für Sessions und Turns. Jede Route liegt unter /v1/sessions und nimmt ein User-Token oder das Session-Cookie an. Siehe Authentifizierung.

Begriff	Bedeutung
Item	Ein Eintrag in einem Turn, zum Beispiel eine Nachricht der Person, eine Antwort des Models, ein Werkzeugaufruf oder ein Werkzeugergebnis.
Revision	`session.revision`. Eine Zahl, die bei jeder Änderung an der Session steigt.
Timeline	Alle gespeicherten Versions einer Session. Jede Änderung fügt eine neue Version hinzu.
Timeline head	`session.head`. Die ID der aktuellen Version auf der Timeline.
Version	Ein gespeicherter Punkt im Verlauf. Eine Version ändert sich nie, nachdem OpenBot sie gespeichert hat.

Die meisten Schreibzugriffe brauchen expected. Das ist die Revision, die du zuletzt gesehen hast. Wenn sich die Session seitdem geändert hat, antwortet OpenBot mit 409 und SessionConflict. Lies die Session neu und versuche es noch einmal.

Eine Session erstellen

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Trip plan"}' \
  https://api.example.com/v1/sessions

Alle Felder sind optional. title ist ein kurzer Name. OpenBot entfernt Leerzeichen am Anfang und Ende. Der Rest muss 1 bis 100 Zeichen haben. Eine Session ohne Titel hat kein Feld title in ihren metadata. agent ist die ID des Agents, der in der Session arbeitet. Ohne dieses Feld arbeitet dein Main Agent darin. Du brauchst agents.delegate für den Agent. settings kann mode und model enthalten. Ohne Model nutzt die Session das Model des Agents. Wenn keiner von beiden ein Model gibt, gibt OpenBot 400 mit SessionModelInvalid und dem Grund missing zurück. Es gibt kein Standard-Model. Siehe Models. Wie du die Memory-Schalter setzt, steht unter Memory. Das Erstellen einer Session ruft kein Model auf. OpenBot antwortet mit 201 und der Ansicht der Session. Hier ist eine kurze Form davon:

{
  "session": {
    "id": "a41c9e0f",
    "revision": 0,
    "head": "v-7d21",
    "metadata": { "title": "Trip plan" },
    "settings": { "mode": "build" },
    "pending": [],
    "turns": [],
    "inheritedTurns": []
  },
  "state": {
    "version": { "id": "v-7d21" },
    "value": { "conversation": { "history": [] } }
  },
  "agent": "agt_3f9a…",
  "kind": "direct",
  "parent": null,
  "response": null,
  "activity": "inactive"
}

agent ist der Agent der Session. kind ist direct für Arbeit, die ein Client gestartet hat, delegated für Arbeit, die ein anderer Agent abgegeben hat, review für eine Session, in der ein Agent über einen Request entscheidet, trigger für Arbeit, die ein Trigger gestartet hat, und channel für einen Chat eines Channel. parent nennt die Session, den Turn und den Werkzeugaufruf, die abgegebene Arbeit gestartet haben. Siehe Delegation.

response ist die Antwort des neuesten Turns. activity ist active, solange ein Turn auf diesem Server läuft, inactive, wenn nichts läuft, und historical, wenn ein gespeicherter Turn sagt, dass er läuft, aber kein Server ihn ausführt.

Sessions auflisten und lesen

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  "https://api.example.com/v1/sessions?archived=false"

Die Liste ist ein Array von Zusammenfassungen. Jede Zusammenfassung hat session, agent, kind, parent, status (Idle, Running, Waiting, Completed, Failed oder Interrupted), turn, eine kurze response und activity. Lass archived weg, um alle Sessions zu bekommen. Füge agent=<id> hinzu, um die Sessions eines Agents aufzulisten. Review-Sessions fehlen in der Liste, außer du fügst kind=review hinzu.

GET /v1/sessions/:sessionId gibt die volle Ansicht zurück. Lesen startet nie Arbeit.

Um auf eine Änderung zu warten, nutze Long Polling (eine Anfrage, die auf eine Änderung wartet). OpenBot antwortet, wenn die Revision nicht mehr after ist oder wenn die Wartezeit endet. Das längste Warten dauert 30 Sekunden.

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  "https://api.example.com/v1/sessions/$SESSION/wait?after=3&timeoutMs=30000"

Umbenennen, archivieren und löschen

curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":3,"title":"Trip to Rome","archived":true}' \
  https://api.example.com/v1/sessions/$SESSION

expected ist die aktuelle revision der Session. Für title gelten dieselben Regeln wie beim Erstellen einer Session. Sende "title": null, um den Titel zu entfernen. Lass ein Feld weg, um seinen Wert zu behalten.

DELETE /v1/sessions/:sessionId entfernt die Session und antwortet mit 204. Ihre Session Agents werden archiviert. Wenn ein Turn läuft, antwortet OpenBot mit 409 und SessionBusy.

Einen Turn starten

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"input":"Plan three days in Rome."}' \
  https://api.example.com/v1/sessions/$SESSION/turns

Feld	Bedeutung
`expected`	Pflicht. Die aktuelle `session.revision`.
`input`	Pflicht. Text oder eine Liste von Nachrichten der Person (siehe unten).
`stream`	Optional. `true` sendet Live-Ereignisse. Siehe Die Antwort streamen.
`background`	Optional. Nur `true` ist erlaubt. Jeder Turn läuft im Hintergrund.
`overrides`	Optional. Einstellungen nur für diesen Turn: `mode` und `model`.

input nimmt nur Text an. Diese drei Formen bedeuten dasselbe:

"Plan three days in Rome."

[{ "role": "user", "content": "Plan three days in Rome." }]

[
  {
    "type": "message",
    "role": "user",
    "content": [{ "type": "input_text", "text": "Plan three days in Rome." }]
  }
]

Unbekannte Felder ergeben 400.

Antwort im Hintergrund

Ohne stream antwortet OpenBot sofort mit 202. Die Antwort hat status: "in_progress":

{
  "id": "t-19aa",
  "object": "response",
  "created_at": 1792486800,
  "session": "a41c9e0f",
  "version": "v-7d21",
  "background": true,
  "status": "in_progress",
  "output": [],
  "error": null,
  "incomplete_details": null
}

Die Arbeit geht weiter, nachdem die Anfrage endet. Lies das Ergebnis später mit GET /v1/sessions/:sessionId (das Feld response), mit der Warte-Route oder mit GET /v1/sessions/:sessionId/turns/:turnId. Der letzte status ist completed, incomplete, failed oder cancelled. Jedes Item in output ist eine Nachricht des Assistenten mit Teilen vom Typ output_text. usage zeigt die Tokens.

Die Antwort streamen

Mit "stream": true antwortet OpenBot mit 200 und Server-Sent Events (SSE). SSE ist ein einfaches Format für einen Strom von Ereignissen über HTTP.

curl -N -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"input":"Plan three days in Rome.","stream":true}' \
  https://api.example.com/v1/sessions/$SESSION/turns

event: response.output_text.delta
data: {"type":"response.output_text.delta","session":"a41c9e0f","turn":"t-19aa","step":1,"sequence_number":4,"item_id":"i-02","output_index":0,"content_index":0,"delta":"Day 1: ","logprobs":[]}

Die Ereignisse kommen in dieser Reihenfolge: response.created, response.in_progress, response.output_item.added, response.content_part.added, viele response.output_text.delta, response.output_text.done, response.content_part.done, response.output_item.done. Das letzte Ereignis ist eins von response.completed, response.incomplete, response.failed oder response.cancelled. Der Stream beobachtet den Turn nur. Wenn du ihn schließt, läuft der Turn weiter.

Häufige Fehler

Status	Fehler	Wann
`400`	`SessionModelInvalid`	Das Model in `overrides` gibt es nicht.
`404`	`SessionNotFound`	Du hast keine Session mit dieser ID.
`409`	`SessionBusy`	Die Session hat schon einen Turn, der nicht fertig ist.
`409`	`SessionConflict`	`expected` ist veraltet, oder der Turn konnte nicht starten.
`503`	`SessionExecutionUnavailable`	OpenBot hat kein Model, um den Turn auszuführen.
`503`	`SessionStorageUnavailable`	OpenBot erreicht seine Datenbank nicht.

Ein Turn kann auch anhalten und warten: auf eine Entscheidung über eine Fähigkeit oder auf Arbeit, die er an einen anderen Agent abgegeben hat. Sein Status ist dann Waiting. Das Warten übersteht einen Neustart des Servers. Siehe Requests und Delegation.

Turns und Items lesen

GET /v1/sessions/:sessionId/turns listet Turn-Einträge auf, den ältesten zuerst. Nutze limit (1 bis 100, Standard 50) und after (eine Turn-ID). Die Antwort ist { "items": [...], "next": "<turnId>" | null }. Die Liste enthält auch Turns, die ein Fork aus der Quell-Session kopiert hat.

GET /v1/sessions/:sessionId/turns/:turnId gibt { "turn": {...}, "response": {...} } zurück. Der Turn-Eintrag hat status, settings, steps, usage, start und end. start ist die Version vor dem Turn. end ist die Version danach. Ein Turn, der für ein anderes Member als den Besitzer der Session arbeitet, hat author, die User-ID dieses Members. In einem Channel ist es die Person, die die Nachricht geschrieben hat.

GET /v1/sessions/:sessionId/turns/:turnId/items listet die Items eines Turns auf, mit denselben Feldern after und limit. Jedes Item hat id, content und origin (session, turn, step).

Steer, Queue und Unterbrechen

Steer (lenken) fügt einem laufenden Turn eine Nachricht hinzu. Der Agent liest sie bei seinem nächsten Schritt.

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Keep it cheap."}' \
  https://api.example.com/v1/sessions/$SESSION/turns/$TURN/steer

OpenBot antwortet mit 202 und session, turn, item, revision und version. Wenn der Turn nicht läuft, bekommst du 409. Ein Turn mit author nimmt Steer-Nachrichten nur von diesem Author an.

Queue (einreihen) speichert eine Nachricht für später: POST /v1/sessions/:sessionId/queue mit { "input": ..., "expected"?: <revision> }. Wenn der aktuelle Turn endet, startet OpenBot die nächste eingereihte Nachricht als neuen Turn. Die Antwort ist 202 mit session, item und revision.

Unterbrechen stoppt einen Turn: POST /v1/sessions/:sessionId/turns/:turnId/interrupt mit dem Body {}. Der Status des Turns wird Interrupted, und der Status der Antwort wird cancelled. Ein Turn, der schon beendet ist, ergibt 409.

Fortsetzen räumt nach einem Neustart auf: POST /v1/sessions/:sessionId/resume. Wenn ein gespeicherter Turn noch sagt, dass er läuft, aber kein Server ihn ausführt (activity: "historical"), markiert OpenBot ihn als Interrupted. Es führt den Turn nicht noch einmal aus. Ein Turn mit Waiting bleibt unberührt, weil sein Warten gespeichert ist.

Todo-Liste

Eine Session hat eine Todo-Liste (eine Liste offener Aufgaben). Der Agent führt sie mit dem Werkzeug openbot_todos, wenn seine Arbeit mehr als einen Schritt hat. Jeder Eintrag hat eine id, einen content und einen status: pending, in_progress oder done. Nur ein Eintrag kann zur selben Zeit in_progress sein.

Solange ein Eintrag nicht done ist, arbeitet der Agent weiter. Wenn der Agent den Turn mit offenen Einträgen beenden will, fügt OpenBot eine Erinnerung mit den offenen Einträgen hinzu. Dann macht der Agent noch einen Schritt. OpenBot erinnert ihn nur einmal für jeden Stand der Liste. Wenn der Agent also wieder aufhört und sich die Liste nicht geändert hat, endet der Turn.

Lies die Liste mit GET /v1/sessions/:sessionId/todos:

{
  "items": [
    { "id": "read", "content": "Read the open issues", "status": "done" },
    { "id": "fix", "content": "Fix the login bug", "status": "in_progress" }
  ]
}

Ersetze die ganze Liste mit PUT /v1/sessions/:sessionId/todos. Sende die Version und die Revision der Session, die du gelesen hast:

{
  "expected": "<version>",
  "revision": 7,
  "items": [
    { "id": "fix", "content": "Fix the login bug", "status": "pending" }
  ]
}

Die Antwort ist die Ansicht der Session. Eine alte Version oder Revision gibt 409 mit SessionConflict zurück. Das gilt auch für eine Liste, in der zwei Einträge dieselbe id haben oder mehr als ein Eintrag in_progress ist.

Die Liste ist Teil der Timeline. Ein Fork oder eine Wiederherstellung einer älteren Version hat die Liste dieser Version.

Warten

Ein Agent kann mit dem Werkzeug openbot_wait warten. Er gibt seconds an, oder until mit Datum und Uhrzeit, zum Beispiel 2026-10-23T09:00:00Z. Der Turn wird Waiting. Wenn die Zeit kommt, bekommt der Werkzeugaufruf { "waited": true, "at": "<time>" }, und der Turn geht weiter.

OpenBot speichert jedes Warten. Nach einem Neustart läuft das Warten bis zu seiner Zeit weiter. Ein Warten, dessen Zeit vorbei ist, während kein Server lief, geht gleich nach dem Start weiter. Ein Unterbrechen des Turns beendet sein Warten.

Um auf die Arbeit mehrerer Agents zugleich zu warten, gibt der Agent ihnen ihre Aufgaben mit mehreren openbot_delegate-Aufrufen im selben Schritt. Der Turn geht weiter, wenn alle fertig sind. Siehe Delegation.

Plan-Modus

Im Modus plan sieht der Agent nach, aber er ändert noch nichts. Er bekommt nur die Werkzeuge, die nur lesen: die Agent-Werkzeuge, die Agents auflisten und lesen, App-Ressourcen und Prompts, und die App-Werkzeuge, die die Organisation in appReadRules nennt. Er bekommt auch das Todo-Werkzeug und das Warte-Werkzeug.

Wenn der Plan fertig ist, ruft der Agent openbot_submit_plan mit den Schritten als Todo-Liste und einer kurzen Zusammenfassung auf. OpenBot speichert die Liste und erstellt einen Request für die Fähigkeit plans.run. Der Turn wartet.

Wenn der Request erlaubt wird, wechselt die Session in den Modus build. Ein neuer Turn startet mit allen Werkzeugen, und der Agent führt den Plan aus.
Wenn er abgelehnt wird, bekommt der Agent den Grund und bleibt im Modus plan.

Die Einstellung für die Erlaubnis sagt, wer antwortet und was passiert, wenn niemand rechtzeitig antwortet:

{ "approver": "person", "timeoutMs": 600000, "onTimeout": "run" }

Feld	Werte	Was es tut
`approver`	`chain`, `person`	`chain` fragt den Entscheider über dem Agent. So kann ein Grant oder eine Rule antworten. `person` fragt immer den Menschen.
`timeoutMs`	1 Sekunde bis 7 Tage	Wie lange der Request wartet.
`onTimeout`	`run`, `stay`	`run` führt den Plan aus, wenn niemand rechtzeitig antwortet. `stay` lässt die Session im Modus `plan`.

Du kannst sie an vier Stellen festlegen. Die genaueste Stelle, die etwas festlegt, gewinnt, auch wenn sie lockerer ist:

Die Session: planApproval, wenn du sie erstellst, oder mit PATCH /v1/sessions/:sessionId. Sende null, um es zu entfernen.
Der Agent: planApproval am Agent.
Du: PATCH /v1/me/settings mit { "expectedVersion": 0, "planApproval": { ... } }. Lies deine Einstellungen mit GET /v1/me/settings.
Die Organisation: planApproval in ihren Einstellungen. Das ist nur der Standard. Es kann eine lockerere Einstellung nicht verbieten.

Models und Ausführungsmodus

GET /v1/sessions/:sessionId/models zeigt die Models, die du wählen kannst:

{
  "selected": {
    "_tag": "Config.Selection",
    "provider": "development",
    "model": "mock-text"
  },
  "providers": [
    { "id": "development", "name": "Development scenarios (simulated)" }
  ],
  "models": [
    {
      "_tag": "Config.Model",
      "provider": "development",
      "id": "mock-text",
      "name": "mock-text (simulated)",
      "reasoningEfforts": [],
      "serviceTiers": []
    }
  ]
}

Wähle ein Model für die Session mit PUT /v1/sessions/:sessionId/model:

{
  "expected": 4,
  "selection": {
    "_tag": "Config.Selection",
    "provider": "development",
    "model": "mock-slow"
  }
}

Eine falsche Wahl ergibt 400 mit SessionModelInvalid. Der reason ist provider-not-found, model-not-found oder unsupported-option. Um ein Model nur für einen Turn zu nutzen, setze die Auswahl in overrides.model, wenn du den Turn startest. Wie OpenBot seine Models bekommt, steht unter Models.

Der Ausführungsmodus ist build oder plan. build ist der normale Modus: Der Agent macht die Arbeit. Im Modus plan schreibt der Agent zuerst einen Plan. Siehe Plan-Modus. Setze den Modus mit PUT /v1/sessions/:sessionId/mode und { "expected": 4, "mode": "plan" }, oder mit settings.mode, wenn du die Session erstellst. OpenBot speichert den Modus in der Session und kopiert ihn in die settings jedes neuen Turns.

PUT /v1/sessions/:sessionId/settings ersetzt alle Einstellungen auf einmal: { "expected": 4, "settings": { "mode": "build" } }.

Fork von einer Version

Ein Fork (Abzweigung) erstellt eine neue Session, die bei einer Version einer anderen Session beginnt. Die Quell-Session ändert sich nicht.

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":"v-7d21","title":"Rome, plan B"}' \
  https://api.example.com/v1/sessions/$SESSION/fork

Alle Felder sind optional: version, title und settings. Ohne title behält der Fork den Titel seiner Quelle. Ohne version beginnt der Fork beim neuesten vollständigen Punkt. OpenBot antwortet mit 201 und der Ansicht der neuen Session. Ihr session.forkedFrom nennt die Quell-Session und die Version.

Versions findest du mit GET /v1/sessions/:sessionId/versions. Den Verlauf bei einer Version siehst du mit GET /v1/sessions/:sessionId/history?version=<versionId>.

Eine Antwort neu erzeugen

Um eine neue Antwort auf dieselbe Frage zu bekommen, mach einen Fork von der Version vor diesem Turn. Dann starte einen neuen Turn mit derselben Eingabe.

Lies den Turn mit GET /v1/sessions/$SESSION/turns/$TURN. Merke dir turn.start. turn.input listet die IDs der Eingabe-Items. Lies ihren Text mit der Route für Items.
Mach einen Fork mit { "version": "<turn.start>" }. Merke dir die neue session.id und session.revision.
Starte in der neuen Session einen Turn mit demselben input.

Export und Import

GET /v1/sessions/:sessionId/record exportiert die ganze Session als einen Eintrag. Der Eintrag hat formatVersion, session, versions und messages.

PUT /v1/sessions/:sessionId/record importiert einen Eintrag. Der Body ist { "record": {...}, "expected": ... }:

Nutze "expected": null, um aus dem Eintrag eine neue Session zu erstellen.
Um eine bestehende Session zu ersetzen, setze expected auf ihr aktuelles Objekt session aus GET /v1/sessions/:sessionId.

Die session.id des Eintrags muss zum Pfad passen. Wenn nicht, antwortet OpenBot mit 400 und SessionInvalidRecord. Wenn ein Turn läuft, antwortet OpenBot mit 409 und SessionBusy. Ein Import stellt nur Daten wieder her. Er startet keinen Turn neu.

Alle Felder findest du in der Sessions-Referenz.