Skip to main content
An agent is created from one template version and owns one sandbox; a session is an endless conversation inside it. This page covers both from your backend. The examples assume a server SDK client named client (Go, Python) or paddock (TypeScript), created as in the quickstart.

Create an agent

  • template must name an exact version, name@version.
  • metadata is 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.
The returned agent carries its effective 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:
Deleting an agent ends every running turn, deletes all its sessions with their history, revokes their tokens, and deletes the sandbox with its files:

Create a session

Every field is optional: 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 send raises its error; before sending again, look for the message in the session’s events, since the first attempt may have been stored.
A user message is waiting while its seq is above the session’s processedSeq.

Stop a turn

stop stores a stop.requested event and returns it.
What it does depends on the session’s state: 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 by seq:
The answer is { data, hasMore }. Turns are also readable as records, with their status, inputs, attempt, error, retry time, and timing:
A turn’s model usage is in its 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

Deleting a session ends its running turn, drops its waiting messages, deletes its events and turns, revokes its tokens, and ends its open streams. The agent and its files stay.

Lists and pagination

Lists of templates, agents, sessions, turns, capability entries, model providers, triggers, and deliveries take limit (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; .data and .next_cursor are the first page.
  • Go: List returns an iterator over every item; ListPage returns one page.
The other lists are not paged this way. 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 }.