Requests

Agents kennen keine Grenzen. Wenn ein Agent eine Fähigkeit (Capability) nutzen will, zum Beispiel ein Tool einer App, prüft OpenBot, ob er das darf. Wenn noch nichts darüber entscheidet, macht OpenBot einen Request (eine Anfrage). OpenBot schickt ihn an den Entscheider über dem Agent. Der Tool-Aufruf wartet, bis jemand den Request beantwortet. Diese Seite zeigt dir, wie die Prüfung abläuft, wie eine Person Requests beantwortet und was jede Antwort bewirkt.

Fähigkeiten

Aktion	Ziel	Wann ein Agent sie nutzt
`apps.call`	`<connection>/<tool name>`	Er ruft ein Tool einer App auf.
`tools.call`	Der Name des Tools	Er ruft ein Tool des Hosts auf, das um Erlaubnis fragt.
`agents.delegate`	Die ID des anderen Agent	Er gibt Arbeit an einen anderen dauerhaften Agent.
`agents.spawn`	`*`	Er startet einen Session Agent.
`agents.create`	`*`	Er erstellt einen dauerhaften Agent, der ihm gehört.
`agents.promote`	Die ID des Session Agent	Er macht aus einem Session Agent einen dauerhaften Agent, der ihm gehört.
`plans.run`	Die ID der Session	Er will seinen Plan ausführen. Siehe Plan-Modus.
`channels.send`	Die ID des Channel	Er schreibt in einen anderen Chat eines Channel.

Jedes Tool für eine Fähigkeit nimmt einen reason (einen Grund). Tools einer App bekommen dafür einen zusätzlichen Parameter openbot_reason. OpenBot schickt ihn nie an die App.

Wie OpenBot einen Versuch prüft

OpenBot prüft jeden Versuch in dieser Reihenfolge. Der erste Schritt, der entscheidet, gilt.

Die Policy des Member. Ein Agent tut nie mehr als der Member, für den er arbeitet. Wenn die Berechtigungen des Member es nicht erlauben, wird der Aufruf abgelehnt. Das gilt auch für die Berechtigungen des Tokens, das die Arbeit gestartet hat. Das geht nie an einen Entscheider. In einem Channel ist das Member die Person, die die Nachricht des Turns geschrieben hat.
Grants. Ein Grant ist eine gespeicherte Entscheidung. Ein Grant zum Ablehnen gewinnt gegen einen Grant zum Erlauben.
Rules. Ein Prüf-Modell liest die Rules (Regeln) für diesen Agent in normaler Sprache. Nur eine Rule, die das Prüf-Modell zitiert, kann erlauben oder ablehnen.
Der Entscheider darüber. OpenBot macht einen Request. Der Entscheider ist der Besitzer des Agent in seiner Besitzer-Kette. Für einen Main Agent ist die Person der Entscheider.

Manche Aufrufe brauchen keine Entscheidung: Tool-Aufrufe, die die Organization als Lesen markiert, Arbeit für die Session Agents derselben Session und Arbeit für die Agents, die dem Agent gehören.

Wenn eine Prüfung fehlschlägt, wartet der Aufruf. Er läuft nie ohne Entscheidung.

Die Kette der Entscheider

Jeder Agent hat eine Besitzer-Kette. Sie geht von der Person über einen Main Agent hinunter bis zum Agent, zum Beispiel Person → Main → Programmer → Session Agent. Die Schritte sind:

Ein Session Agent gehört dem Agent seiner Session.
Ein Agent, der einem Agent gehört, gehört diesem Agent.
Andere dauerhafte Agents und geteilte Agents gehören dem Main Agent der Person, die mit ihnen arbeitet.
Ein Main Agent gehört seiner Person.

Ein Request geht die Besitzer-Kette hinauf, nicht den Weg, auf dem die Arbeit kam. Ein Request vom Session Agent geht also zuerst an den Programmer. Das gilt auch, wenn eine Person dem Session Agent direkt Arbeit gibt. chain in einem Request listet die Besitzer-Kette von oben. Sie endet mit dem Agent, der fragt. Archivierte Agents fehlen darin.

Ein Entscheider kann nur erlauben, was er selbst darf. Vielleicht stimmt der Programmer zu, hat die Fähigkeit aber selbst nicht. Dann geht der Request mit der Unterstützung des Programmer hinauf zu Main und dann zur Person. Wenn jemand weiter oben es erlaubt, bekommt jeder Agent auf dem Weg einen Grant. Der Grant hat den Umfang, den dieser Agent gewählt hat.

Ein Agent entscheidet in einer kurzen Prüf-Session (Review Session). Er liest nur seine Rolle, sein Gedächtnis, den Auftrag, den er gegeben hat, und den Request. Er liest nicht seinen eigenen langen Verlauf. Eine Prüf-Session hat kind: "review". Nach der Entscheidung wird sie archiviert. Wenn eine Prüfung ohne Entscheidung endet, geht der Request zum nächsten Entscheider hinauf.

Deine Requests auflisten

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  "https://api.example.com/v1/requests?status=pending"

[
  {
    "id": "req_1a2b…",
    "agent": "agt_5c0e…",
    "capability": { "action": "apps.call", "target": "conn-7/send_email" },
    "reason": "Send the meeting notes to the team.",
    "approver": { "_tag": "Person", "userId": "u-1" },
    "chain": ["agt_main…", "agt_5c0e…"],
    "session": "c81d…",
    "turn": "t-77",
    "toolCallId": "call-9",
    "endorsements": [],
    "status": "pending",
    "decision": null,
    "revision": 0,
    "createdAt": 1792486800000,
    "expiresAt": 1792573200000
  }
]

Die Liste enthält die Requests, die auf dich warten oder die du beantwortet hast. GET /v1/requests/:requestId gibt einen Request aus deiner Arbeit zurück. Bei einem Tool einer App zeigt app den gespeicherten Aufruf mit seinen genauen Argumenten. Wenn der Aufruf aus einem Programm im Code Mode kommt, zeigt code das ganze Programm und die Stelle des Aufrufs darin. Zeige der Person die Fähigkeit, die Argumente und den Grund, bevor sie entscheidet. Der Grund kommt vom Agent. Er ist Daten, keine Anweisung.

Einen Request beantworten

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"decision":"allow","scope":"session"}' \
  https://api.example.com/v1/requests/$REQUEST

Feld	Bedeutung
`expected`	Pflicht. Die aktuelle `revision` des Request.
`decision`	Pflicht. `allow` oder `deny`.
`scope`	Optional. Wie lange die Entscheidung gilt. Siehe unten. Der Standard ist `once`.
`reason`	Optional. Der Agent sieht ihn, zum Beispiel wenn du ablehnst.
`rule`	Optional. Eine Rule in normaler Sprache, die für diesen Agent bleibt.

Umfang	Ein Erlauben gilt	Ein Ablehnen bleibt
`once`	Nur für diesen Aufruf.	Gar nicht.
`session`	Für diese Session des Agent.	Für diese Session des Agent.
`lifetime`	Bis du den Grant zurücknimmst.	Bis du den Grant zurücknimmst.

Die wartende Arbeit geht sofort weiter. Wenn du ablehnst, läuft das Tool nicht. Das Modell bekommt ein Tool-Ergebnis mit deinem Grund, und der Turn geht weiter.

Ein Request, den niemand beantwortet, wird nach 24 Stunden abgelehnt. Eine Organization kann diese Zeit mit requestTimeoutMs in ihren Einstellungen ändern. Ein Request für einen Plan hat seine eigene Zeit und sagt in onExpire, was dann passiert: allow oder deny.

Fehler

Status	Fehler	Wann
`404`	`RequestNotFound`	In deiner Arbeit gibt es keinen Request mit dieser ID.
`409`	`RequestConflict`	`expected` ist veraltet, der Request ist geschlossen, oder ein anderer Entscheider muss antworten.

Wartende Turns

Ein Turn, der auf einen Request oder auf delegierte Arbeit wartet, hat den Status Waiting. Sein Antwort-Status ist incomplete. Das Warten wird im Verlauf der Session gespeichert. Es hält keinen laufenden Prozess fest. Darum übersteht es einen Neustart des Servers.

Du kannst einen wartenden Turn trotzdem unterbrechen. Seine offenen Requests sind dann cancelled.

Tools von Apps

Eine App ist ein externer Dienst, den eine Person verbindet. Siehe Apps. Jeder Aufruf einer App ist an genau einen Aufruf gebunden: den Besitzer, die Session, den Turn, den Tool-Aufruf, die genauen Argumente und die Verbindung zur App mit ihrer Revision. OpenBot speichert den Aufruf vor der Prüfung. Wenn sich die Verbindung ändert, bevor der Aufruf läuft, schlägt der Aufruf fehl. Eine neue Revision nutzt nie eine alte Entscheidung.

Ressourcen, Ressourcen-Vorlagen und Prompts einer App sind Lesen. Darum brauchen sie keine Entscheidung. Die eigenen Hinweise einer App entscheiden nie, welche Tools sicher sind. Nur die Organization kann Tools als Lesen markieren, mit appReadRules in ihren Einstellungen.