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?
optionalabortSignal: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?
optionalaccountIdOf: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?
optionalapiKey:string
Defined in: packages/agentos/src/api/generateObject.ts:207
Override the API key instead of reading from environment variables.
baseUrl?
optionalbaseUrl:string
Defined in: packages/agentos/src/api/generateObject.ts:210
Override the provider base URL (useful for local proxies or Ollama).
budget?
optionalbudget: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?
optionalcache: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?
optionalcustomModelParams: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?
optionaleffort: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?
optionalfallbackProviders: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?
optionalmaxAttempts: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?
optionalmaxRetries: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?
optionalmaxTokens:number
Defined in: packages/agentos/src/api/generateObject.ts:195
Hard cap on output tokens.
messages?
optionalmessages:Message[]
Defined in: packages/agentos/src/api/generateObject.ts:189
Full conversation history.
model?
optionalmodel: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()?
optionalonAttempt: (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
Returns
void
onFallback()?
optionalonFallback: (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?
optionalpolicyTier:"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?
optionalprompt:string
Defined in: packages/agentos/src/api/generateObject.ts:173
User prompt. Convenience alternative to building a messages array.
provider?
optionalprovider: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?
optionalrequestTimeout: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?
optionalschemaCacheTtl:"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?
optionalschemaDescription: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?
optionalschemaName: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?
optionalserviceTier:"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?
optionalsessionId: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?
optionalsource: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?
optionalstore: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?
optionalsystem: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?
optionaltemperature:number
Defined in: packages/agentos/src/api/generateObject.ts:192
Sampling temperature forwarded to the provider (0-2 for most providers).
thinking?
optionalthinking: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.