StepController selects the next model/tool configuration; a ContextPolicy builds a request from history; a CompletionPolicy accepts, revises, stops, or requests input after the driver returns.
Select tools and model roles
A controller may implementprepareRun(ctx) and prepareStep({ index, tools }, ctx). Either returns StepOverrides or undefined.
Opaque provider continuation data prevents unsafe model-role switching. Do not treat role selection as a way to move arbitrary provider state between models.
Reflect on an answer and summarize long context
This complete configuration uses a separate role for policy calls. It constructs a runtime; it does not execute a request until you callrun().
services.controlModel(). These calls use shared budgets, cancellation, and events, but skip task controllers, context projection, and middleware to avoid recursion. They cannot execute tools or reuse task continuation state. The active task model role and tools remain unchanged.
Reflection options and decisions
reflectionPolicy() requires modelRole and host-authored criteria. Optional id defaults to agentium/reflection, maxInputBytes to 65,536, and maxTokens to 1,024. Limits must be positive safe integers; the role’s binding must allow maxTokens.
The model must return a valid JSON decision. Unknown fields, malformed JSON, an empty reason, an invalid action, or a revision without an instruction fail evaluation. Responses over 64 KB are rejected.
Every decision has
reason and optional evidence: string[]. Only revise has instruction. At the revision limit the runtime returns stopped with revision_limit. New tool effects in revisions require allowRevisionEffects: true in addition to normal grants and execution policy.
Summary context options
summaryContextPolicy() requires modelRole and maxContextTokens, an estimate for the projected request including retained turns, instructions, and summary. Its defaults are:
The policy avoids a summary call when the request already fits. It preserves host system messages and complete recent turn groups, including tool-call/result and provider continuation structure. An indivisible recent turn, source group, or summary that cannot fit causes an error rather than silently producing a malformed request.
Summarization changes the model request projection. It does not overwrite canonical session history.
Implement your own policies
ContextPolicy.project({ history, entries }, ctx) returns { messages, provenance }. Each provenance item identifies a sourceId, whether it was included, and an optional reason. Preserve valid message groups and supply provenance matching the projected sources.
CompletionPolicy.evaluate({ text, structured, revision }, ctx) returns a CompletionDecision. A deterministic policy can return a decision without a model call. Use controlModel only when model evaluation adds value and bind its role explicitly.
See all controller and policy types, grants and budgets, and source context.