Skip to content
OpenBot

Agents

An Agent is a worker with a role, such as a programmer, a writer or a designer. Each Agent has its own instructions, its own Sessions and its own long-term memory. Agents give work to each other, so each one keeps its attention on its own task. This page shows the kinds of Agents and the routes under /v1/agents. Every route accepts a user token or the session cookie. See Authentication.

Three kinds of Agents

Kind Owner Lives What it is for
main One member As long as the member Acts for the person. Does simple work itself and gives work away.
persistent A member, or the organization Until you archive it A lasting worker with a role. It learns from its work over time.
subagent One Session As long as the Session that owns it A helper for one line of work. It keeps its context in that Session.

Every member has exactly one Main Agent. OpenBot makes it the first time it is needed. A Session that you create without an Agent belongs to your Main Agent.

A subagent is “almost lasting”. An Agent starts it with a tool while it works. The subagent keeps its context while its Session lasts, so the Agent can give it work many times. When you delete the Session, its subagents are archived too. You can promote a useful subagent to a lasting Agent.

Every Session belongs to one Agent. See Sessions. How Agents give work to each other is on Delegation.

No limits that an Agent knows

Agents have no list of things they may do. An Agent just tries. When it tries something new for the first time, such as starting a subagent or calling an App tool, the decider above it decides. See Requests. The decisions are kept, so the limits of each Agent grow from real work.

Make an Agent

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
Field Meaning
name Required. A short name, up to 100 characters.
role Required. What the Agent does, in one line. Other Agents read it to choose workers.
instructions Required. The lasting instructions of the Agent, like a job description.
model Optional. The default model for new Sessions of this Agent.
shared Optional. true makes an organization Agent that every member can use.

OpenBot returns 201 with the 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 is Member, Organization or Session. A shared Agent works with the permissions and the App connections of the member who uses it, never with those of the person who made it.

List, read and change Agents

GET /v1/agents lists your Main Agent, your own Agents and the shared Agents that you may use. Add ?archived=false to hide archived Agents. Add ?session=<id> to list the subagents of one Session.

GET /v1/agents/:agentId returns one Agent.

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 is the current revision. You can change name, role, instructions, model (send null to remove it) and archived. The Main Agent cannot be archived.

Promote a subagent

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

The subagent becomes a lasting Agent of the member. OpenBot also adds the lasting entries of its Session memory to its Agent memory.

What an Agent knows in each Turn

OpenBot adds these to the instructions of every Turn:

  • the name, role and instructions of the Agent,
  • the person it works with now, with their name and member ID,
  • rules about privacy: what the Agent learned from one person may be private, so it tells another person only what is clearly shared,
  • for a Session with work from another Agent, how to send the result back,
  • the active entries of its Agent memory.

Permissions

Permission Lets you
agents.read Read Agents, their memory, Rules and Grants.
agents.write Make and change Agents, their memory, Rules and Grants.
agents.delegate Give work to an Agent, from a client or from another Agent.

Your own Agents are below your member key. Shared Agents are below openbot.org.<org>.agent. Members may read and use shared Agents. Administrators may also change them. See Permissions.

Errors

Status Error When
400 AgentInvalid The change is not allowed, such as archiving a Main Agent.
403 PermissionDenied You may read the Agent, but not change or use it.
404 AgentNotFound There is no Agent with this ID that you may read.
409 AgentConflict expected is old. Read the Agent again and retry.
503 AgentStorageUnavailable OpenBot cannot reach its database.