Zum Inhalt springen
OpenBot

Agents

Ein Agent ist ein Arbeiter mit einer Rolle, zum Beispiel ein Programmierer, ein Autor oder ein Designer. Jeder Agent hat seine eigenen Anweisungen, seine eigenen Sessions und sein eigenes Langzeitgedächtnis. Agents geben sich gegenseitig Arbeit. So bleibt jeder bei seiner eigenen Aufgabe. Diese Seite zeigt die Arten von Agents und die Routen unter /v1/agents. Jede Route nimmt ein User-Token oder das Session-Cookie an. Siehe Authentifizierung.

Drei Arten von Agents

Art Besitzer Lebt Wofür er da ist
main Ein Member So lange wie das Member Handelt für die Person. Macht einfache Arbeit selbst und gibt Arbeit ab.
persistent Ein Member, die Organisation oder ein anderer Agent Bis du ihn archivierst Ein dauerhafter Arbeiter mit einer Rolle. Er lernt mit der Zeit aus seiner Arbeit.
session Eine Session So lange wie die Session, der er gehört Ein Helfer für einen Arbeitsstrang. Er behält seinen Kontext in dieser Session.

Jedes Member hat genau einen Main Agent (Haupt-Agent). OpenBot erstellt ihn, wenn er zum ersten Mal gebraucht wird. Eine Session, die du ohne Agent erstellst, gehört deinem Main Agent.

Ein neuer Main Agent hat kein Model. Setze sein model, bevor du eine Session ohne eigenes Model erstellst. Siehe Models.

Ein Session Agent ist “fast dauerhaft”. Ein Agent startet ihn während der Arbeit mit einem Werkzeug. Der Session Agent behält seinen Kontext, solange seine Session besteht. So kann der Agent ihm viele Male Arbeit geben. Wenn du die Session löschst, werden auch ihre Session Agents archiviert. Du kannst einen nützlichen Session Agent zu einem dauerhaften Agent machen.

Ein Agent kann auch selbst dauerhafte Agents besitzen. Siehe Agents, die Agents besitzen.

Jede Session gehört zu einem Agent. Siehe Sessions. Wie Agents sich gegenseitig Arbeit geben, steht unter Delegation.

Keine Grenzen, die ein Agent kennt

Agents haben keine Liste von Dingen, die sie tun dürfen. Ein Agent probiert es einfach. Wenn er zum ersten Mal etwas Neues versucht, zum Beispiel einen Agent erstellen oder ein App-Werkzeug aufrufen, entscheidet die Stelle über ihm. Siehe Requests. Die Entscheidungen werden gespeichert. So wachsen die Grenzen jedes Agents aus echter Arbeit.

Einen Agent erstellen

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Programmer","role":"Writes and reviews TypeScript code","instructions":"Write small, tested changes. Explain each change in one short paragraph."}' \
  https://api.example.com/v1/agents
Feld Bedeutung
name Pflicht. Ein kurzer Name. OpenBot entfernt Leerzeichen am Anfang und Ende. Der Rest muss 1 bis 100 Zeichen haben.
role Pflicht. Was der Agent tut, in einer Zeile. Andere Agents lesen sie, um Arbeiter auszuwählen.
instructions Pflicht. Die dauerhaften Anweisungen des Agents, wie eine Stellenbeschreibung.
model Optional. Das Model der Sessions dieses Agents, wenn eine Session kein eigenes wählt.
planApproval Optional. Wie die Pläne dieses Agents erlaubt werden. Siehe Plan-Modus.
shared Optional. true erstellt einen Agent der Organisation, den jedes Member nutzen kann.
agent Optional. Die ID des Agents, dem der neue Agent gehört. Du kannst es nicht zusammen mit shared nutzen.

OpenBot antwortet mit 201 und dem Agent:

{
  "id": "agt_5c0e…",
  "kind": "persistent",
  "owner": { "_tag": "Member", "userId": "u-1" },
  "name": "Programmer",
  "role": "Writes and reviews TypeScript code",
  "instructions": "Write small, tested changes. …",
  "archived": false,
  "revision": 0,
  "createdAt": 1792486800000,
  "updatedAt": 1792486800000
}

owner ist Member, Organization, Session oder Agent. Ein gemeinsamer Agent arbeitet mit den Berechtigungen und App-Verbindungen des Members, das ihn nutzt. Er arbeitet nie mit denen der Person, die ihn erstellt hat.

Agents auflisten, lesen und ändern

GET /v1/agents listet deinen Main Agent, deine eigenen Agents und die gemeinsamen Agents auf, die du nutzen darfst. Füge ?archived=false hinzu, um archivierte Agents auszublenden. Füge ?session=<id> hinzu, um die Session Agents einer Session aufzulisten. Füge ?agent=<id> hinzu, um die Agents aufzulisten, die einem Agent gehören.

GET /v1/agents/:agentId gibt einen Agent zurück.

Terminal window
curl -X PATCH -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":0,"instructions":"Write small changes with tests first."}' \
  https://api.example.com/v1/agents/$AGENT

expected ist die aktuelle revision. Du kannst name (mit denselben Regeln wie oben), role, instructions, model (sende null, um es zu entfernen) und archived ändern. Den Main Agent kann man nicht archivieren. Wenn du einen Agent archivierst, archiviert OpenBot auch jeden Agent, der ihm gehört, und die Agents darunter. Wenn du die Archivierung aufhebst, kommt nur dieser eine Agent zurück.

Einen Session Agent dauerhaft machen

Terminal window
curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expected":3}' \
  https://api.example.com/v1/agents/$AGENT/promote

Der Session Agent wird ein dauerhafter Agent des Members. Sende agent mit der ID eines Agents, um diesen Agent zu seinem Besitzer zu machen. OpenBot fügt auch die dauerhaften Einträge seines Session-Memorys zu seinem Agent-Memory hinzu.

Ein Agent kann einen Session Agent seiner eigenen Session mit dem Werkzeug openbot_promote_agent dauerhaft machen. Dann gehört er diesem Agent.

Agents, die Agents besitzen

Ein Agent kann dauerhafte Agents besitzen. So kann ein Agent sein eigenes Team bauen, und jedes Teammitglied behält sein eigenes Gedächtnis.

  • Ein Agent erstellt einen Agent, der ihm gehört, mit dem Werkzeug openbot_create_agent. Eine Person erstellt einen mit POST /v1/agents und dem Feld agent.
  • Ein Agent, den ein anderer Agent mit einem Werkzeug erstellt, also ein dauerhafter Agent oder ein Session Agent, bekommt das model des Agents, der ihn erstellt. Der Aufruf des Werkzeugs kann ein anderes model nennen.
  • Der Besitzer ist { "_tag": "Agent", "agent": "<owner ID>", "userId": "<member>" }. userId ist das Member an der Spitze des Besitzer-Baums. Es ist null, wenn die Organisation den obersten Agent besitzt.
  • Ein Agent kann den Agents, die ihm gehören, ohne Request Arbeit geben.
  • Die Besitzer-Kette eines Agents geht über seine Besitzer nach oben bis zu einem Main Agent und dann bis zur Person. Zum Beispiel: Person → Main → Worker → Scout. Requests eines Agents gehen diese Kette hinauf, auch wenn eine Person direkt mit dem Agent arbeitet. Siehe Requests.
  • In der Kette ist der Besitzer eines Agents eines Members oder eines gemeinsamen Agents der Main Agent der Person, die mit ihm arbeitet.

Was ein Agent in jedem Turn weiß

OpenBot fügt diese Dinge zu den Anweisungen jedes Turns hinzu:

  • den Namen, die Rolle und die Anweisungen des Agents,
  • die Person, mit der er gerade arbeitet, mit ihrem Namen und ihrer Member-ID. In einem Channel ist es die Person, die die Nachricht des Turns geschrieben hat,
  • Regeln zum Datenschutz: Was der Agent von einer Person gelernt hat, kann privat sein. Darum sagt er einer anderen Person nur, was klar geteilt ist,
  • bei einer Session mit Arbeit von einem anderen Agent: wie er das Ergebnis zurückschickt,
  • die aktiven Einträge seines Agent-Memorys.

Berechtigungen

Berechtigung Damit kannst du
agents.read Agents lesen, mit ihrem Memory, ihren Rules und Grants.
agents.write Agents erstellen und ändern, mit ihrem Memory, ihren Rules und Grants.
agents.delegate Einem Agent Arbeit geben, von einem Client oder von einem anderen Agent aus.

Deine eigenen Agents liegen unter deinem Member-Schlüssel. Gemeinsame Agents liegen unter openbot.org.<org>.agent. Members dürfen gemeinsame Agents lesen und nutzen. Administratoren dürfen sie auch ändern. Siehe Berechtigungen.

Fehler

Status Fehler Wann
400 AgentInvalid Die Änderung ist nicht erlaubt, zum Beispiel einen Main Agent archivieren.
403 PermissionDenied Du darfst den Agent lesen, aber nicht ändern oder nutzen.
404 AgentNotFound Es gibt keinen Agent mit dieser ID, den du lesen darfst.
409 AgentConflict expected ist veraltet. Lies den Agent neu und versuche es noch einmal.
503 AgentStorageUnavailable OpenBot erreicht seine Datenbank nicht.