Next Turn Params | OpenDunes Docs

Not yet available. The Agent SDK is tracked to be built — today, use the Client SDKs against the live chat completions API. The docs below describe the intended design.

The item list is the agent's memory — it accumulates everything the agent has said and done. nextTurnParams is a lighter channel: a small key-value store that travels from turn to turn but never appears in the item list and is never sent to the model.

Use it for execution metadata — routing hints, budget counters, flags — that your orchestration logic needs but that would add noise to the model's context if included as messages.

Basic usage#

Set nextTurnParams in a callModel() call. They are available as result.nextTurnParams and are automatically forwarded to the next call if you pass result.items as inputItems.

TypeScript

const r1 = await client.callModel({
  model: "google/gemini-2.5-pro",
  messages: initialMessages,
  tools: searchTools,
  nextTurnParams: {
    searchesRemaining: 5,
    preferFastModel: false,
  },
});

// r1.nextTurnParams === { searchesRemaining: 5, preferFastModel: false }
// (decremented/updated by your logic before passing to the next turn)

const r2 = await client.callModel({
  model: r1.nextTurnParams.preferFastModel ? "meta-llama/llama-4-maverick" : "google/gemini-2.5-pro",
  inputItems: r1.items,
  nextTurnParams: {
    ...r1.nextTurnParams,
    searchesRemaining: r1.nextTurnParams.searchesRemaining - 1,
  },
});

Difference from `dynamicParams`#

	`dynamicParams`	`nextTurnParams`
Computed	Each turn, from the item list	Set explicitly per turn
Affects call params	Yes — merges into params	No — side-channel only
Visible to model	No	No
Use for	Adaptive model/temperature	Counters, flags, routing metadata

Combining with stop conditions#

A common pattern: use nextTurnParams to count a resource (tool calls, DA spend, external API calls) and a custom stop condition to halt when the counter is exhausted.

TypeScript

dynamicParams: (items) => ({
  stopConditions: [
    {
      type: "custom",
      check: (result) => result.nextTurnParams?.searchesRemaining <= 0,
    },
  ],
}),

Type safety#

Declare the shape of your next-turn params with a generic type parameter:

TypeScript

interface MyParams {
  searchesRemaining: number;
  preferFastModel: boolean;
}

const result = await client.callModel<MyParams>({
  model: "anthropic/claude-sonnet-5",
  messages: initialMessages,
  nextTurnParams: { searchesRemaining: 5, preferFastModel: false },
});

// result.nextTurnParams is typed as MyParams

Also see#

Dynamic Parameters — compute call params from item history.
Stop Conditions — declarative loop termination.
API Reference — full type definitions.

Basic usage#

Set nextTurnParams in a callModel() call. They are available as result.nextTurnParams and are automatically forwarded to the next call if you pass result.items as inputItems.

TypeScript

const r1 = await client.callModel({
  model: "google/gemini-2.5-pro",
  messages: initialMessages,
  tools: searchTools,
  nextTurnParams: {
    searchesRemaining: 5,
    preferFastModel: false,
  },
});

// r1.nextTurnParams === { searchesRemaining: 5, preferFastModel: false }
// (decremented/updated by your logic before passing to the next turn)

const r2 = await client.callModel({
  model: r1.nextTurnParams.preferFastModel ? "meta-llama/llama-4-maverick" : "google/gemini-2.5-pro",
  inputItems: r1.items,
  nextTurnParams: {
    ...r1.nextTurnParams,
    searchesRemaining: r1.nextTurnParams.searchesRemaining - 1,
  },
});

dynamicParams

nextTurnParams

Computed

Each turn, from the item list

Set explicitly per turn

Affects call params

Yes — merges into params

No — side-channel only

Visible to model

Use for

Adaptive model/temperature

Counters, flags, routing metadata

Combining with stop conditions#

A common pattern: use nextTurnParams to count a resource (tool calls, DA spend, external API calls) and a custom stop condition to halt when the counter is exhausted.

TypeScript

dynamicParams: (items) => ({
  stopConditions: [
    {
      type: "custom",
      check: (result) => result.nextTurnParams?.searchesRemaining <= 0,
    },
  ],
}),

Type safety#

Declare the shape of your next-turn params with a generic type parameter:

TypeScript

interface MyParams {
  searchesRemaining: number;
  preferFastModel: boolean;
}

const result = await client.callModel<MyParams>({
  model: "anthropic/claude-sonnet-5",
  messages: initialMessages,
  nextTurnParams: { searchesRemaining: 5, preferFastModel: false },
});

// result.nextTurnParams is typed as MyParams