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).

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.

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

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).