Choose the execution lifetime first. AgentRuntime runs inside your process; a durable host
accepts work that can outlive the request and resume after restart. Both use the same agent loop.
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to use
Use when you want to write effectful code that looks and behaves like
synchronous code, while still handling asynchronous tasks, errors, and complex
control flow such as loops and conditions.
Generator functions work similarly to async/await but keep errors,
requirements, and interruption in the Effect type. You can yield* values
from effects and return the final result at the end.
Provide the model, toolkit handlers, and runtime services around program. The
travel-planner example
contains the complete setup. output has passed the Agent’s output Schema; finishReason
distinguishes ordinary completion from a budget-exhausted answer.
Use AgentRuntime.stream to consume a Stream of RunEvent values: text, tool activity,
updates, and lifecycle events. Text deltas are provisional. For structured output, wait for
Schema-validated completion before presenting a final answer.
A slow consumer backpressures the bounded event queue. Interrupting an ephemeral stream closes
its execution Scope and interrupts the Run. To observe the same local Run more than once, use
AgentRuntime.start inside Effect.scoped; its handle exposes await, observe, events, and
usageReport. Slow detached observers can fail with a lag error without blocking execution.
Steering enters before the next model request; follow-up enters when the Agent would otherwise
stop. Neither rewrites an active tool call. With restartOnJoinedInput, eligible new input can
cancel a disposable model request and replace it. Clients must clear the affected draft on
ModelRestarted.
run finishes run-local cleanup before returning. stream owns cleanup through consumption;
start belongs to its caller’s Scope. Enclosing application Layers can serve many Runs.
For durable work, disconnecting an observer or interrupting a waiter only detaches that caller.
Use an authorized, persisted abort command to cancel accepted work. A replacement Attempt
receives a fresh duration allowance; cumulative call and usage limits remain separate.
Choose a Node or Cloudflare host for durable execution.
See operations for receipts, observation, and cancellation, and
budgets for limits and usage accounting.
DurableAgentRuntime.layer composes registrations with a SubmissionLedger, ThreadStore,
WakeScheduler, and host authorization. Capture model and tool services when building the Layer.
The storage adapter must provide work discovery, streaming verification, worker-capacity reads,
and peer-message counts; missing capabilities fail Layer construction with ThreadStoreError.
Prompt checkpoints and fresh-admission shortcuts are optional accelerators.
Your host must route each Thread to one process owner and drive recovery after lost wake hints.
Prefer a platform host unless you need to own that scheduling and resource lifetime yourself.