Long-Running Agents

Agents that persist for hours, days, or weeks — a monitoring agent that checks in daily, a project manager that runs for a sprint. Checkpoint an agent's state, resume it later from any checkpoint, and send it new input over time. You only pay for active compute, not idle time.

Checkpointing is explicit today — you call agent.checkpoint() at the points that matter. Interval-based auto-checkpointing and hibernate-on-idle configured at create time are on the roadmap; this page documents what ships now.

Checkpoints

A checkpoint captures the agent's full state (as an infrastructure snapshot) plus application-level metadata you attach — a phase, a progress value from 0 to 1, and any metadata. Save one whenever the agent reaches a meaningful point you'd want to return to.

checkpoint.ts

// Save a checkpoint — a snapshot of the agent's state plus app-level
// metadata about where it is in the work. Call this at meaningful points.
const checkpoint = await agent.checkpoint({
  phase: 'monitoring',
  progress: 0.4,
  metadata: { lastReport: '2026-08-06', itemsProcessed: 128 },
})
console.log(checkpoint.id)         // 'ckpt_a1b2c3'
console.log(checkpoint.snapshotId) // the underlying infrastructure snapshot

// List every checkpoint for this agent (newest first).
const history = await agent.checkpoints()
for (const c of history) {
  console.log(c.phase, c.progress, c.createdAt)
}

Resuming

Resume restores the agent from a checkpoint's underlying snapshot. Call it with no argument to resume from the latest checkpoint, or pass a specific checkpoint id. This is the same resume mechanism used by manual pause() / resume() — there is only one.

resume.ts

// Resume from the most recent checkpoint.
await agent.resume()

// Or resume from a specific checkpoint by id.
await agent.resume({ checkpoint: 'ckpt_a1b2c3' })

Sending input over time

A long-running agent takes input across its whole lifetime. Send it a message and, if it has hibernated while idle, it wakes from its latest checkpoint automatically before the input is delivered — you don't resume by hand first.

send.ts

// Send input to a long-running agent. If it hibernated while idle, this
// wakes it from its latest checkpoint automatically before delivering.
await agent.send({
  type: 'message',
  content: 'Check the latest sales numbers and flag anything unusual.',
})

Tracking progress

Progress reports where the agent is and how long it has lived. totalDuration is wall-clock time since creation; activeDuration is the compute time you're actually billed for — hibernated time is free.

progress.ts

const progress = await agent.progress()
console.log(progress.phase)          // 'monitoring' — your last checkpoint phase
console.log(progress.checkpoints)    // 12 — how many checkpoints exist
console.log(progress.totalDuration)  // '3d 4h'  — wall-clock since the agent was created
console.log(progress.activeDuration) // '2h 15m' — compute time you're actually billed for
console.log(progress.status)         // 'active' | 'hibernated' | 'terminated'

Terminating a long-running agent with agent.terminate() stops it but preserves its checkpoints, so you can inspect or resume from them afterward.

Method reference

agent.checkpoint(opts?)CheckpointDataSave a checkpoint. opts: { phase?, progress?, metadata? }.

agent.checkpoints()CheckpointData[]List all checkpoints for the agent, newest first.

agent.resume(opts?)voidResume from the latest checkpoint, or opts.checkpoint for a specific one.

agent.send(input)voidSend input { type, content, metadata? }; auto-resumes if hibernated.

agent.progress()AgentProgressDataCurrent phase, checkpoint count, and active vs. total duration.

agent.terminate()voidStop the agent; its checkpoints are preserved.