Skip to main content

Interface: GenerateObjectOptions<T>

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

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​

abortSignal?​

optional abortSignal: AbortSignal

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

Ends the call when it aborts: no further attempt or fallback hop starts, and the call rejects with the signal's reason. Forwarded to every attempt's GenerateTextOptions.abortSignal, which hands it to the provider request.


accountIdOf?​

optional accountIdOf: LlmUsageAccountResolver

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

Names the account of a call whose budget names none, forwarded to GenerateTextOptions.accountIdOf and surfaced on the global LLM usage observer event as accountId.


apiKey?​

optional apiKey: string

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

Override the API key instead of reading from environment variables.


baseUrl?​

optional baseUrl: string

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

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


budget?​

optional budget: SpendBudget | SpendBudgetOptions

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

A spend budget for this call and, when the same SpendBudget instance is passed to several calls, for all of them: each attempt's provider call is checked against what is left before it is made and recorded after it, so a refused attempt ends the call with no further attempt.


cache?​

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

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

Per-call prompt-cache control, forwarded to 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); { tail: false } keeps the caller's system markers and the schema block's marker and places no breakpoint on the messages — right for an extraction that re-sends the same instructions with new input each call.


customModelParams?​

optional customModelParams: Record<string, unknown>

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

Provider-specific top-level request fields, forwarded to GenerateTextOptions.customModelParams and spread onto every attempt's request body, a validation retry included, with the same rules as there: a fallback leg gets them minus the fields only another vendor accepts (OpenRouter's routing controls, Gemini's request fields, OpenAI's response_format, Anthropic's output_config), and keys collide last-wins with the typed fields at the provider layer. A passthrough tool_choice, tools or response_format here can change the structured-output route this call takes (generateObject).


effort?​

optional effort: string

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

Reasoning-depth / token-spend control, forwarded to 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:217

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

See​

GenerateTextOptions.fallbackProviders


maxAttempts?​

optional maxAttempts: number

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

The most attempts each generation's call makes, a first and its retries together; the provider's configured count when left out. A validation retry (maxRetries) is a generation of its own, with its own count. Within one attempt, a key-scoped failure on a pool of several keys re-sends the same request with the next usable key, at most once per key, and those sends are not counted.


maxRetries?​

optional maxRetries: number

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

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:195

Hard cap on output tokens.


messages?​

optional messages: Message[]

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

Full conversation history.


model?​

optional model: string

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

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"`

onAttempt()?​

optional onAttempt: (outcome) => void

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

Called once per attempt a generation's call made, with the answer of the attempt's last send (a key hop's earlier answers are not reported), so a caller can settle the attempts it paid for.

Parameters​

outcome​

AttemptOutcome

Returns​

void


onFallback()?​

optional onFallback: (error, fallbackProvider) => void

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

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:240

Caller's intended content policy tier. Forwarded to 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:173

User prompt. Convenience alternative to building a messages array.


provider?​

optional provider: string

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

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:248

Per-call request timeout in milliseconds, forwarded to 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:154

Zod schema defining the expected output shape.


schemaCacheTtl?​

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

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

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:170

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:162

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

Example​

`"PersonInfo"`

serviceTier?​

optional serviceTier: "priority" | "default" | "auto" | "flex"

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

OpenAI service tier, forwarded to GenerateTextOptions.serviceTier and sent as service_tier verbatim on every attempt, a validation retry included. No default: OpenAI then serves the request at the project's configured tier. 'flex' bills at about batch rates but can answer 429 under load; 'priority' is a paid tier. Other providers ignore it.


sessionId?​

optional sessionId: string

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

Per-conversation affinity key, forwarded to 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:361

Opt-in source label forwarded to 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.


store?​

optional store: boolean

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

Sent to OpenAI as store on the request, on /v1/chat/completions and /v1/responses alike, forwarded to GenerateTextOptions.store on every attempt, a validation retry included. Left out, a chat completion sends no store key and a Responses request sends store: false, as before. Other providers ignore it, those built on the OpenAI provider included, which leave it out of the request to their own endpoint. "Chat completions are stored by default for new accounts" (https://developers.openai.com/api/docs/guides/migrate-to-responses), so a call whose output OpenAI must not keep sets store: false.


system?​

optional system: string | SystemContentBlock[]

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

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:192

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:290

Extended-thinking switch, forwarded to 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.