client (Go, Python) or paddock (TypeScript), created as in the quickstart.
Create an agent
templatemust name an exact version,name@version.metadatais up to 50 string pairs of your own. Lists filter by it.- Creating returns before the sandbox exists; the sandbox is created the first time a session needs it.
model, its status (sleeping, waking, awake, or unavailable), its generation (see Capabilities), the capabilities its harness supports, and sessionCount. Read it again with agents.get(id), and list agents, filtered by template (name or name@version) and metadata:
Create a session
A session’s system prompt, environment, and permissions are fixed when it is created; see Configuration. All of an agent’s sessions share its sandbox and its files, and each runs its own turns concurrently with the others.
Send messages
send stores a user message and returns once it is stored. It does not wait for the agent to wake or for a turn to start.
- Any time, from anywhere. Your backend, your frontend, and triggers can all send to one session at any time.
- In order. Messages are processed in the order they were stored (their
seq). A message sent while a turn runs waits; the next turn takes every waiting message together, as one batch. - At most 100 KB of text per message.
- Never retried automatically. A failed
sendraises its error; before sending again, look for the message in the session’s events, since the first attempt may have been stored.
seq is above the session’s processedSeq.
Stop a turn
stop stores a stop.requested event and returns it.
Held messages are those at or below the session’s
heldSeq. A turn that failed and that the agent gave up on holds the waiting messages the same way.
Read the history
A session’s history is its events: its messages, turn starts and ends, stops, configuration changes, and its agent’s availability. Read them as pages byseq:
The answer is
{ data, hasMore }. Turns are also readable as records, with their status, inputs, attempt, error, retry time, and timing:
turn.ended event. To follow a session live from your backend, use session.stream(); see Streaming.
Find sessions by your own keys
paddock does not keep the mapping between your users and sessions; keep it in your own database, or put your keys in a session’s metadata and filter by them.sessions.list lists every session of the project, newest first, across agents:
sessions.list also takes agentId and a creation range, createdAfter (inclusive) and createdBefore (exclusive); agent.sessions.list lists one agent’s. Every metadata key you pass must match exactly. Sessions are not filtered or sorted by status.
A session that a trigger rule created carries its rendered session key as the triggerKey metadata, so sessions.list({ metadata: { triggerKey: "acme/web#42" } }) finds the conversation about pull request 42.
Get and delete a session
Lists and pagination
Lists of templates, agents, sessions, turns, capability entries, model providers, triggers, and deliveries takelimit (default 50, at most 200) and cursor, and return { data, nextCursor }. The SDKs page for you:
- TypeScript:
await list()is the first page;for await (const x of list())iterates every item. - Python: the returned page iterates every item;
.dataand.next_cursorare the first page. - Go:
Listreturns an iterator over every item;ListPagereturns one page.
models.list takes no parameters and returns every model in one page. A session’s events.list is paged by seq, with after, before, types, and limit, and returns { data, hasMore } with no cursor. files.list and memory.list return every entry at once as { data }.