Turns

A Turn is one durable execution. It selects one immutable Agent revision or inline behavior, an explicit tenant, an optional actor user, and independently optional Conversation and MemorySpace coordinates.

Start stored Agent behavior

const agent = await client.agent("support");
const turn = await agent.start("Summarize this request.", {
  tenant: "acme",
  user: "alice",
  idempotencyKey: "ticket-483:summary-v1",
});

start() returns after admission, not settlement. Store turn.id; it is the recovery handle for the work.

Start inline behavior

const runner = client.inline({
  instructions: "Return a concise sentiment label.",
  model: "anthropic/claude-sonnet-5",
  limits: { maxOutputTokens: 40 },
});
 
const result = await runner.run("The issue is finally fixed.", {
  tenant: "acme",
});

Stored and inline sources enter the same execution path. A stored Agent is appropriate for reusable behavior and revision history; inline behavior is appropriate when the behavior belongs to the call site.

Select continuity and memory independently

const result = await agent.run("Continue the investigation.", {
  tenant: "acme",
  user: "alice",
  conversation: {
    key: "ticket-483",
    owner: "tenant",
  },
  memory: {
    scope: "user",
    namespace: "support",
  },
});

Omit conversation for standalone execution. Use memory: { scope: "none" } to disable an Agent's default memory policy for one Turn.

Stream and recover

for await (const update of turn.updates()) {
  render(update.snapshot.status, update.snapshot.text);
}
 
const recovered = client.turn(turn.id, { tenant: "acme", user: "alice" });
const final = await recovered.result();

The same tenant and user context used to access the Turn must be supplied when reconstructing a handle. A disconnected stream or local timeout never implies cancellation.

Control and inspect through the exact client

The facade keeps common execution concise. client.raw().turns exposes the generated HTTP surface for cancel, interrupt, resume, nudges, host-tool results, timeline, traces, and logs. Raw calls preserve exact wire names and require the same tenant/user headers as the Turn.

Cancel discards unfinished work. Interrupt ends at a safe boundary and keeps valid work. Resume raises eligible limits on a budget_hold. See How turns end.