Overview

Thread · conversation and shared state

Root turn · one request, one owner

Step 1
model → tool
← feedback

Step 2
model → child turn
← result

Step 3
model → answer
→ close gate

One final outcome

Next request → next turn → fresh execution

A new model call is a step within the turn. A new user request starts another root turn.

A turn is one invocation of an agent with an input, a caller, and an execution budget. It can contain several model steps, tool calls, and child turns before it settles. The agent that owns the root turn remains responsible for the final response to that request.

Know the units of work

Unit	Meaning
Thread	The conversation identity used to group messages and state. It can contain many turns.
Turn	One agent invocation, with its own budget, transcript, and outcome.
Model step	One iteration of the turn's model loop. Its chain can make multiple provider attempts through retry or fallback.
Tool call	One requested operation. A model step can request several calls.
Child turn	A delegated agent invocation, awaited by its immediate caller.

A tool result does not start a new root turn. It becomes feedback within the current turn. Delegation opens a child turn, then returns its result to the parent's existing execution.

Follow the lifecycle

The caller starts a turn. Keel checks admission, assembles context, executes the model/tool loop, and evaluates completion. Expected execution endings return a TurnOutcome; configuration errors and unexpected application exceptions can still throw.

const outcome = await runtime.runTurn({
  agent: assistant,
  ambient,
  envelope,
  budget: { steps: 8 },
});

if (outcome.kind === "completed") {
  console.log(outcome.payload.text);
}

The values above come from your application. A step budget grants ordinary model-loop iterations; it does not promise eight successful provider calls or limit the entire delegation tree to eight operations.

Output does not wait for settlement: when a tier streams, text parts land on the wire as they arrive, and hooks.onEvent sees them live. The outcome at the end is still the only word on how the turn ended.

Keep execution separate from completion

Suppose the model emits part of a document, then reaches a length limit. That output may already be visible. The turn still needs a successful continuation or it settles as truncated. Receiving text is not evidence of a completed request.

The Harness explains the checks that enforce execution and completion. Turns explains the lifecycle and the result your application handles.

Work with turns

Guide	What you'll learn
Starting a turn	Supply an agent, request, trusted ambient context, and explicit budget.
Inside a turn	Follow model steps, automatic feedback, and transcript growth.
Outcomes and completion	Handle each ending without treating partial output as success.
Nested turns	Understand parent/child ownership and separate execution records.
History and records	Understand what persists and what the next turn receives.

Inspect in Studio

Select a root turn in TURNS, then follow its model steps in MODEL. Compare a step with several tool calls to a delegation that creates a separate child record in TURN RECORDS. The final outcome belongs to the turn, not to an individual provider response.

Next: Starting a turn.

Know the units of work

Follow the lifecycle

Keep execution separate from completion

Work with turns

Inspect in Studio

On this page