Skip to main content

Interface: GenerateObjectOptions<T>

Defined in: packages/agentos/src/api/generateObject.ts:118

Options for a generateObject call.

At minimum, schema and either prompt or messages must be supplied. Provider/model resolution follows the same rules as generateText.

Example​

const opts: GenerateObjectOptions<typeof mySchema> = {
  schema: z.object({ name: z.string(), age: z.number() }),
  prompt: 'Extract: "John is 30 years old"',
};

Type Parameters​

T​

T extends ZodType

The Zod schema type that defines the expected output shape.

Properties​

apiKey?​

optional apiKey: string

Defined in: packages/agentos/src/api/generateObject.ts:189

Override the API key instead of reading from environment variables.

baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/api/generateObject.ts:192

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

cache?​

optional cache: false | { ttl?: "5m" | "1h"; }

Defined in: packages/agentos/src/api/generateObject.ts:260

Per-call prompt-cache control, forwarded to import('./generateText.js').GenerateTextOptions.cache. false opts this call out of ALL cache marking (the schema block's marker included — right for one-shot extractions); { ttl: '1h' } puts a 1-hour TTL on the provider's auto markers (the moving message-tail).

effort?​

optional effort: string

Defined in: packages/agentos/src/api/generateObject.ts:239

Reasoning-depth / token-spend control, forwarded to import('./generateText.js').GenerateTextOptions.effort. On effort-capable models the provider emits it as output_config.effort (Anthropic) or reasoning_effort (OpenAI o-series / GPT-5). Dropped on models that don't support it.

fallbackProviders?​

optional fallbackProviders: FallbackProviderEntry[]

Defined in: packages/agentos/src/api/generateObject.ts:199

Ordered fallback providers tried when the primary fails with a retryable error. When undefined, auto-built from env keys. Pass [] to disable.

See​

import('./generateText.js').GenerateTextOptions.fallbackProviders

maxRetries?​

optional maxRetries: number

Defined in: packages/agentos/src/api/generateObject.ts:186

Number of times to retry when JSON parsing or Zod validation fails. Each retry appends the error details to the conversation so the model can self-correct.

Default​

2

maxTokens?​

optional maxTokens: number

Defined in: packages/agentos/src/api/generateObject.ts:177

Hard cap on output tokens.

messages?​

optional messages: Message[]

Defined in: packages/agentos/src/api/generateObject.ts:171

Full conversation history.

model?​

optional model: string

Defined in: packages/agentos/src/api/generateObject.ts:133

Model identifier. Prefer the plain model name with provider set; the combined "provider:model" string is also accepted.

Example​

`"gpt-4o"` (with `provider: 'openai'`), `"gpt-4o-mini"`

onFallback()?​

optional onFallback: (error, fallbackProvider) => void

Defined in: packages/agentos/src/api/generateObject.ts:204

Called when a fallback provider is about to be tried.

Parameters​

error​

Error

fallbackProvider​

string

Returns​

void

policyTier?​

optional policyTier: "safe" | "standard" | "mature" | "private-adult"

Defined in: packages/agentos/src/api/generateObject.ts:222

Caller's intended content policy tier. Forwarded to import('./generateText.js').GenerateTextOptions.policyTier so structured-output callers get the same policy-aware fallback behavior as plain text callers — mature/private-adult requests auto-route refusals to an uncensored OpenRouter model instead of hard-failing on a content_policy_violation.

Particularly relevant here because OpenAI's strict structured- output mode (response_format: json_schema) is the most aggressively-moderated path on the platform; a mature story extraction tagged with policyTier: 'mature' that the primary refuses walks on to the tier's uncensored OpenRouter models, which take the looser json_object mode that generateObject uses for non-OpenAI providers.

prompt?​

optional prompt: string

Defined in: packages/agentos/src/api/generateObject.ts:155

User prompt. Convenience alternative to building a messages array.

provider?​

optional provider: string

Defined in: packages/agentos/src/api/generateObject.ts:125

Provider name. When supplied without model, the default text model for the provider is resolved automatically.

Example​

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

requestTimeout?​

optional requestTimeout: number

Defined in: packages/agentos/src/api/generateObject.ts:230

Per-call request timeout in milliseconds, forwarded to import('./generateText.js').GenerateTextOptions.requestTimeout. Structured-output callers that emit long strings (e.g. codegen TSX) raise the abort window for this call without slowing the provider's default failover for chat / narration traffic.

schema​

schema: T

Defined in: packages/agentos/src/api/generateObject.ts:136

Zod schema defining the expected output shape.

schemaCacheTtl?​

optional schemaCacheTtl: "5m" | "1h"

Defined in: packages/agentos/src/api/generateObject.ts:270

TTL for the schema block's own cache marker (the block this call appends after the caller's system). The schema bytes are stable per call SITE, so sites whose calls gap more than 5 minutes (human-paced pipelines, slow loops) should set '1h' — otherwise the entry expires between calls and every call re-writes the prefix at the write premium. Defaults to the 5-minute marker (previous behavior). Ignored when cache is false.

schemaDescription?​

optional schemaDescription: string

Defined in: packages/agentos/src/api/generateObject.ts:152

Description of the schema, injected into the system prompt alongside the JSON Schema definition.

Example​

`"Information about a person extracted from unstructured text."`

schemaName?​

optional schemaName: string

Defined in: packages/agentos/src/api/generateObject.ts:144

Human-readable name for the schema, injected into the system prompt to give the model context about what it is generating.

Example​

`"PersonInfo"`

sessionId?​

optional sessionId: string

Defined in: packages/agentos/src/api/generateObject.ts:282

Per-conversation affinity key, forwarded to import('./generateText.js').GenerateTextOptions.sessionId. OpenRouter emits it as session_id for provider sticky routing — upstream prompt caches are host-scoped, so a load-balanced multi-call pipeline otherwise cold-misses the cache a prior call wrote on a different host. Pass a stable id per logical session (blueprint/build id for codegen loops, conversation id for chat extraction). Providers without an affinity concept ignore the field.

source?​

optional source: string

Defined in: packages/agentos/src/api/generateObject.ts:292

Opt-in source label forwarded to import('./generateText.js').GenerateTextOptions.source and surfaced on the global LLM usage observer event. Hosts tag their cost/telemetry rows with it (e.g. 'codegen_tool', 'narrator_state_extractor') — without it every structured-output call rolls up under the generic surface bucket.

system?​

optional system: string | SystemContentBlock[]

Defined in: packages/agentos/src/api/generateObject.ts:168

System prompt. The schema extraction instructions are appended to this, so any custom system context is preserved.

Accepts a plain string (single system message) or an ordered array of SystemContentBlock entries. When an array is supplied, caller cacheBreakpoint flags are preserved on each block and a final non-cached block is appended with the JSON schema + formatting rules. This enables Anthropic prompt caching on the stable prefix while letting the per-call schema vary freely.

temperature?​

optional temperature: number

Defined in: packages/agentos/src/api/generateObject.ts:174

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

thinking?​

optional thinking: false | { budgetTokens: number; }

Defined in: packages/agentos/src/api/generateObject.ts:251

Extended-thinking switch, forwarded to import('./generateText.js').GenerateTextOptions.thinking. false turns thinking off with the model's own off shape (Sonnet 5.5 takes between_tools, at effort high or below); Opus 5.5, Fable and Mythos always think. Omitted keeps the model's default, which is thinking on for Opus 5 and later, Sonnet 5 and later, Fable and Mythos. Thinking tokens count toward maxTokens, so a structured call on a thinking model needs room for both.