Dynamic turns

Use dynamic values when later model turns should respond to application context or earlier tool results. A value can be fixed or computed from the current turn.

Choose a model at runtime

type ResearchContext = {
  fast: boolean;
};

const agent = createAgent<string, string, ResearchContext>({
  id: "research-agent",
  model: ({ context }) =>
    context?.fast ? "phaseo/free" : "anthropic/claude-sonnet-4",
  instructions: ({ numberOfTurns }) =>
    `Research turn ${numberOfTurns}. Cite the evidence you use.`,
});

The agent definition accepts dynamic model, models, instructions, temperature, maxOutputTokens, and topP values.

Update application context from a tool

Tools can store information for later turns with context.setContext():

const chooseMode = defineTool({
  id: "choose-mode",
  async execute(input: { fast: boolean }, context) {
    context.setContext({ fast: input.fast });
    return { selected: input.fast ? "fast" : "thorough" };
  },
});

Keep context small and serializable when a run may be persisted and continued later.

Override only the next turn

Use nextTurnParams when a tool should change the immediately following request without permanently changing the agent definition:

const broadenSearch = defineTool({
  id: "broaden-search",
  nextTurnParams: {
    temperature: 0.3,
    maxOutputTokens: 2_000,
  },
  async execute() {
    return { broadened: true };
  },
});

Next-turn values can change the model, instructions, temperature, maximum output tokens, top-p sampling, or available tools.

Start Here

Build

Observe

Reference

Choose a model at runtime

Update application context from a tool

Override only the next turn

​Choose a model at runtime

​Update application context from a tool

​Override only the next turn

​Related guides

Choose a model at runtime

Update application context from a tool

Override only the next turn

Related guides