GenerationOptions

Exhaustive API reference for GenerationOptions — model behavior parameters for temperature, sampling, tokens, and headers.

Set at the agent level as defaults and override per session or via session.update().

import type { GenerationOptions } from "experimental-agent";

type GenerationOptions = {
  maxSteps?: number;
  temperature?: number;
  topK?: number;
  topP?: number;
  frequencyPenalty?: number;
  presencePenalty?: number;
  maxOutputTokens?: number;
  headers?: Record<string, string>;
};

Parameters

Parameter	Type	Default	Description
`maxSteps`	`number`	Unlimited	Max tool-use steps per assistant response. Each tool call counts as a step.
`temperature`	`number`	Model default	Sampling temperature (0–2 typical). Higher = more random.
`topK`	`number`	Model default	Top-K sampling. Consider only the K most likely tokens.
`topP`	`number`	Model default	Top-P (nucleus) sampling. Consider smallest set of tokens whose cumulative probability ≥ P.
`frequencyPenalty`	`number`	Model default	Penalize tokens based on frequency in the output so far.
`presencePenalty`	`number`	Model default	Penalize tokens that have already appeared.
`maxOutputTokens`	`number`	Model default	Maximum tokens the model can generate in a single response.
`headers`	`Record<string, string>`	—	Provider-specific HTTP headers passed to the model API.

Usage at agent level

Set defaults for all sessions:

import { agent } from "experimental-agent";

const myAgent = agent("my-agent", {
  model: "anthropic/claude-opus-4.6",
  generation: {
    maxSteps: 20,
    temperature: 0.7,
    maxOutputTokens: 4096,
  },
});

Usage at session level

Override when creating a session:

const session = myAgent.session(chatId, {
  generation: {
    maxSteps: 5,
    temperature: 0.2,
  },
});

Override later with session.update

Change generation options on an existing session:

await session.update({
  generation: {
    temperature: 0.1,
    maxSteps: 10,
  },
});

Merging behavior

Session-level options merge with agent-level options. Session values override agent values for the same keys:

const myAgent = agent("my-agent", {
  generation: { maxSteps: 20, temperature: 0.7 },
});

const session = myAgent.session(chatId, {
  generation: { maxSteps: 5 },
});
// Effective: { maxSteps: 5, temperature: 0.7 }

maxSteps limits how many tool-use rounds the agent can perform per turn. Each round: model generates → may call tools → model continues. When the limit is reached, the response ends even if the model would call more tools.

generation: { maxSteps: 10 }

Use maxSteps to control cost and latency for tool-heavy agents.

headers

Provider-specific headers are passed through to the model API. Use for custom headers, API keys, or provider-specific options:

generation: {
  headers: {
    "X-Custom-Header": "value",
    "X-API-Key": process.env.MODEL_API_KEY ?? "",
  },
}