Skip to main content

Interface: GenerateObjectOptions<T>

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

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

Override the API key instead of reading from environment variables.

baseUrl?​

optional baseUrl: string

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

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

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

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

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

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

Hard cap on output tokens.

messages?​

optional messages: Message[]

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

Full conversation history.

model?​

optional model: string

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

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

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

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 NSFW story extraction tagged with policyTier: 'mature' will pre-empt the 422 by routing to Hermes 3 (which honors the looser json_object mode that generateObject falls back to for non-OpenAI providers).

prompt?​

optional prompt: string

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

User prompt. Convenience alternative to building a messages array.

provider?​

optional provider: string

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

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

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

Zod schema defining the expected output shape.

schemaCacheTtl?​

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

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

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

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

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

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

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

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

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