Skip to main content

Interface: GenerateTextOptions

Defined in: packages/agentos/src/api/generateText.ts:200

Properties​

_responseFormat?​

optional _responseFormat: Record<string, unknown> | { type: string; }

Defined in: packages/agentos/src/api/generateText.ts:372

Internal

Used by generateObject and AgentSession.send (with responseSchema) to forward a provider-specific response_format payload to the provider. Not part of the public API.

Shape varies by provider: OpenAI accepts json_object or json_schema, Anthropic uses an internal _agentosUseToolForStructuredOutput marker that AnthropicProvider routes to forced tool_use, Gemini uses a _gemini.responseSchema extra. The provider implementations consume whatever shape is here.

apiKey?​

optional apiKey: string

Defined in: packages/agentos/src/api/generateText.ts:244

Override the API key instead of reading from environment variables.

baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/api/generateText.ts:246

Override the provider base URL (useful for local proxies or Ollama).

chainOfThought?​

optional chainOfThought: string | boolean

Defined in: packages/agentos/src/api/generateText.ts:258

Chain-of-thought instruction prepended to the system prompt when tools are available. Encourages the model to reason explicitly before choosing an action.

  • false (default) — no CoT injection.
  • true — inject the default CoT instruction.
  • string — inject a custom CoT instruction.

fallbackProviders?​

optional fallbackProviders: FallbackProviderEntry[]

Defined in: packages/agentos/src/api/generateText.ts:318

Ordered list of fallback providers to try when the primary provider fails with a retryable error (HTTP 402/429/5xx, network errors, auth failures).

Default behavior (omit / undefined): auto-build the canonical fallback chain for the primary provider via buildFallbackChain, filtered to providers that have API keys present in the environment. No import needed — fallback is on by default.

Strict mode ([]): explicitly opt out of fallback. The primary provider's error is re-thrown after exhausting any provider-internal retries. Use this when billing isolation, capability auditing, or provider-pinned testing requires a single-provider guarantee.

Custom chain (array of entries): specify exactly which providers (and optional model overrides) to try, in order. Each entry's model defaults to the provider's text-generation default from PROVIDER_DEFAULTS when omitted. Providers are tried left-to-right; the first successful response wins.

Examples​

const result = await generateText({
  provider: 'anthropic',
  prompt: 'Hello',
});
// On retryable Anthropic failure, walks anthropic → openai → gemini → ...
const result = await generateText({
  provider: 'anthropic',
  prompt: 'Hello',
  fallbackProviders: [],
});
const result = await generateText({
  provider: 'anthropic',
  prompt: 'Hello',
  fallbackProviders: [
    { provider: 'openai', model: 'gpt-4o-mini' },
    { provider: 'openrouter' },
  ],
});

hostPolicy?​

optional hostPolicy: HostLLMPolicy

Defined in: packages/agentos/src/api/generateText.ts:343

Host-level routing hints that can be forwarded into the model router without requiring callers to construct raw router params directly.

maxSteps?​

optional maxSteps: number

Defined in: packages/agentos/src/api/generateText.ts:238

Maximum number of agentic steps (LLM calls) to execute before returning. Each tool-call round trip counts as one step. Defaults to 1.

maxTokens?​

optional maxTokens: number

Defined in: packages/agentos/src/api/generateText.ts:242

Hard cap on output tokens. Provider-dependent default applies when omitted.

messages?​

optional messages: Message[]

Defined in: packages/agentos/src/api/generateText.ts:221

Full conversation history. Appended before prompt when both are supplied.

model?​

optional model: string

Defined in: packages/agentos/src/api/generateText.ts:215

Model identifier. Accepted in two formats:

  • "provider:model" — legacy format (e.g. "openai:gpt-4o"), still fully supported.
  • Plain model name (e.g. "gpt-4o-mini") when provider is also set.

Either provider or model (or an API key env var for auto-detection) is required.

onAfterGeneration()?​

optional onAfterGeneration: (result) => Promise<void | GenerationHookResult>

Defined in: packages/agentos/src/api/generateText.ts:355

Called after each LLM generation step. Can check output against guardrails, redact PII, or transform the response. Return a modified result to transform output, or void to pass through.

Parameters​

result​

GenerationHookResult

Returns​

Promise<void | GenerationHookResult>

onBeforeGeneration()?​

optional onBeforeGeneration: (context) => Promise<void | GenerationHookContext>

Defined in: packages/agentos/src/api/generateText.ts:349

Called before each LLM generation step. Can inject memory context into messages, sanitize input via guardrails, or modify the prompt. Return a modified context to transform input, or void to pass through.

Parameters​

context​

GenerationHookContext

Returns​

Promise<void | GenerationHookContext>

onBeforeToolExecution()?​

optional onBeforeToolExecution: (info) => Promise<ToolCallHookInfo | null>

Defined in: packages/agentos/src/api/generateText.ts:360

Called before each tool execution. Can modify arguments, apply permission checks, or return null to skip the tool call entirely.

Parameters​

info​

ToolCallHookInfo

Returns​

Promise<ToolCallHookInfo | null>

onFallback()?​

optional onFallback: (error, fallbackProvider) => void

Defined in: packages/agentos/src/api/generateText.ts:326

Callback invoked when a fallback provider is about to be tried after the primary (or a previous fallback) failed. Useful for logging or metrics.

Parameters​

error​

Error

The error that triggered the fallback.

fallbackProvider​

string

The provider identifier being tried next.

Returns​

void

planning?​

optional planning: boolean | PlanningConfig

Defined in: packages/agentos/src/api/generateText.ts:267

Enable plan-then-execute mode. When true (or a PlanningConfig), an upfront LLM call decomposes the task into numbered steps before the tool-calling loop begins. The plan is injected into the system prompt so the model executes with full awareness of the strategy.

Set to false or omit to skip planning entirely (the default).

prompt?​

optional prompt: string

Defined in: packages/agentos/src/api/generateText.ts:217

Single user turn to append after any messages. Convenience alternative to building a messages array.

provider?​

optional provider: string

Defined in: packages/agentos/src/api/generateText.ts:207

Provider name. When supplied without model, the default text model for the provider is resolved automatically from the built-in defaults registry.

Example​

`"openai"`, `"anthropic"`, `"ollama"`

router?​

optional router: IModelRouter

Defined in: packages/agentos/src/api/generateText.ts:333

Optional model router for intelligent provider/model selection. When provided, the router's selectModel() is called before provider resolution. The router result overrides model/provider. If the router returns null, falls back to standard resolution.

routerParams?​

optional routerParams: Partial<ModelRouteParams>

Defined in: packages/agentos/src/api/generateText.ts:338

Routing hints passed to the model router. Extracted automatically from system prompt and tool names when not provided.

system?​

optional system: string | SystemContentBlock[]

Defined in: packages/agentos/src/api/generateText.ts:219

System prompt injected as the first message. Accepts a plain string or structured blocks with cache breakpoints.

temperature?​

optional temperature: number

Defined in: packages/agentos/src/api/generateText.ts:240

Sampling temperature forwarded to the provider (0–2 for most providers).

tools?​

optional tools: AdaptableToolInput

Defined in: packages/agentos/src/api/generateText.ts:233

Tools the model may invoke.

Accepted forms:

  • named high-level tool maps
  • external tool registries (Record, Map, or iterable)
  • prompt-only ToolDefinitionForLLM[]

Prompt-only definitions are visible to the model but return an explicit tool error if the model invokes them without an executor.

usageLedger?​

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/generateText.ts:248

Optional durable usage ledger configuration for helper-level accounting.