Starting a run
#A durable run needs the agent's name and store:
const runId = await support.start('Sort the open tickets by urgency.', {
thread: 'triage',
user: 'team',
})
// Status, steps, credits, the messages so far, the answer or pending calls.
const run = await support.get(runId)
for await (const entry of support.events(runId)) console.log(entry.event.type)
await support.cancel(runId) // it ends cancelled at its next heartbeat
start() returns the run's id at once, and the run goes on without the caller. Its status is queued, running, paused, succeeded, failed or cancelled. A run that paused for approval goes on with support.resumeRun(runId, { approve: [callId] }). Of two decisions at once, one runs the calls and the other throws RunNotPausedError.
Recovery after a crash
#await support.recover() // when your app starts, then every half minute:
setInterval(() => {
support.recover().catch((error) => console.error('recover', error))
}, 30_000)
- Every step is saved before its tools run, so a run continues from its last saved step, the model's turn with its private parts (
replay). - A running run renews its lease every 5 seconds while it works. After 20 seconds without a renewal, another process may take the run over.
- A run whose process died 3 times fails.
durable: { leaseMs, heartbeatMs, maxAttempts }on the agent changes these. - A tool call that was running when its process died runs again, with the same
idempotencyKey. Key every write on it, and the second attempt finds the first. - Each agent recovers, resumes and shows only the runs it started, by its
name. Renaming an agent leaves its runs and threads behind.
Your queue
#By default a run executes in the process that started it. To spread runs over workers, give the agent an executor that hands the run's id to your queue, and let the worker call execute(runId):
import { Queue, Worker } from 'bullmq'
const queue = new Queue('ai-runs', { connection })
const support = playcode.ai.agent({
name: 'support',
store,
model,
system,
tools,
executor: (runId) => {
const job = { jobId: runId, removeOnComplete: true, removeOnFail: true }
// A run the queue lost is queued again by recover().
queue.add('run', { runId }, job).catch((error) => console.error(error))
},
})
new Worker('ai-runs', (job) => support.execute(job.data.runId), {
connection,
})
Any process runs a queued run by its id. Two workers that take the same run at once run it once: one claim wins. The SDK queues a run again after an approval, a cancel of a paused run and a crash, so a finished job must free its id: hence removeOnComplete and removeOnFail.
More than one process
#A run's events reach its page through the agent's events bus. The default, memoryEventBus(), is one process's memory. When a page's request can reach another process than the run, pass a RunEventBus that every process shares: publish, subscribe and close. A new Cloud app passes one on Redis when REDIS_URL is set, with a BullMQ executor beside it.
Your store
#A store is twelve reads and writes over your app's database, and one optional write:
| Method | Does |
|---|---|
loadThread, saveThread |
A conversation; a save is conditional on the version it read |
createRun, getRun |
A durable run |
claimRun |
Takes a queued run, or one past its lease, in one conditional write |
updateRun |
Writes a run only while the same attempt holds it |
appendRunMessages (optional) |
Adds a step's messages to a run, on the same condition as updateRun. With it, a run writes each step once; without it, the run writes all its messages at every step |
requeueRun |
Puts a paused run back in the queue, once: an approval |
requestCancel |
Marks a run to stop |
findStaleRuns |
One agent's runs that no live process holds |
listThreads |
One user's threads with one agent, last updated first |
addUserSpend, userSpend |
What one user spent in a UTC day, for per-user limits |
Every write that can race is conditional. That is what keeps two processes from running one run, and an approved call from running twice. A store keeps each message whole: a model's turn carries replay, and a store that keeps only the fields it knows sends the next run's turns back without their thinking. memoryStore() is the reference implementation, and agentStoreContract from @playcode/sdk/testing checks yours: see Testing with the SDK. A new Cloud app ships a store on Prisma, with the tables AiThread, AiRun and AiUserSpend.
Threads
#- A thread is its agent's and its user's own:
support.history('triage', { user: 'team' })reads it. - A thread keeps every message, each model's turn with its
replay, and the brief of a long conversation. Read it on your server: the chat endpoint takesreplayout before a page reads a message. - A thread takes one run at a time:
start()throwsThreadBusyErrorwhile another is in progress. - Once a run ends, no tool call in its thread is left without a result: a run cancelled or failed before a call ran answers that call "Not run". A run that waits for approval holds its calls open until the decision.
Private parts
#A model's turn in messages carries replay: its step's private parts, such as Claude's thinking and Gemini's signatures, and any note the run added before it, such as a brake's correction. They are sealed with a key derived from your secret key, so no reader of your database, a log or a page can read them, and no one can change them. Keep each message whole, replay included, and the next run sends the earlier turns back as they went out. replay is opaque: never edit it.
It goes back only where the model's maker accepts it:
- Claude's thinking goes to any Claude model, with the exact conversation, instructions and tools it was made with. After a fold, an edit or a new
system, an earlier turn's thinking stays out. The run's own steps go as they went out: a tool round in progress keeps its thinking. - Gemini's signatures go back only to the model that wrote them.
- OpenAI's output items stay inside one run.
A turn whose text or calls your app changed goes back without its private parts, and so does one that another app's key sealed. A replay event counts each such turn by its reason. A message without replay, written by an older SDK, goes back as before. The chat endpoint takes replay out of every message and event a page reads; keep it out of a page of your own too.
Limits
#- The store is yours to keep: Playcode does not host conversations or runs.
- A run executes on your app's compute. A schedule, such as a nightly run, is your app's own timer or queue calling
start(). memoryStore()andmemoryEventBus()lose everything on a restart: they are for tests and a first try.