Interface: GenerateObjectOptions<T>

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

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

Override the API key instead of reading from environment variables.

---

baseUrl?

optional baseUrl: string

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

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

---

fallbackProviders?

optional fallbackProviders: FallbackProviderEntry[]

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

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

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

Hard cap on output tokens.

---

messages?

optional messages: Message[]

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

Full conversation history.

---

model?

optional model: string

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

Model identifier. Accepts "provider:model" or plain model name with provider.

Example

`"openai:gpt-4o"`, `"gpt-4o-mini"`

---

onFallback()?

optional onFallback: (error, fallbackProvider) => void

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

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

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

User prompt. Convenience alternative to building a messages array.

---

provider?

optional provider: string

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

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

Example

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

---

schema

schema: T

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

Zod schema defining the expected output shape.

---

schemaDescription?

optional schemaDescription: string

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

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

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

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

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