> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Output

> Get a validated, typed object back from an agent instead of free text

When you need data rather than prose, pass an `outputSchema` to a run. The agent loop runs to completion, coerces the final answer to your schema, and returns a validated object — typed against the schema you defined. The schema is an [ArkType](https://arktype.io) assertion built with `Assert` from `@ooneex/validation`.

## Asking for an object

Define the shape, pass it as `outputSchema`, and type the call with the schema's inferred type:

```typescript theme={null}
import { Assert } from "@ooneex/validation";

const ProductSchema = Assert({
  name: "string",
  price: "number",
  description: "string",
});

const product = await chat.run<typeof ProductSchema.infer>({
  prompt: "Generate a product for an e-commerce store.",
  outputSchema: ProductSchema,
});

console.log(product.name, product.price); // typed and validated
```

Without a schema, `run` returns the assistant's text as a `string`. With one, it returns the validated object — the result is coerced and checked before it reaches you, so a malformed answer fails loudly rather than slipping through.

## Richer schemas

Anything ArkType expresses works — optional fields, unions, arrays, and constraints:

```typescript theme={null}
const ReviewSchema = Assert({
  sentiment: "'positive' | 'neutral' | 'negative'",
  score: "0 <= number <= 10",
  tags: "string[]",
  "summary?": "string",
});

const review = await chat.run<typeof ReviewSchema.infer>({
  prompt: "Analyze this customer review: …",
  outputSchema: ReviewSchema,
});
```

## With tools

Structured output and [tools](/ai/agents/tools) combine: the agent can call tools across the loop to gather what it needs, then shape the final answer into your schema. The object you get back reflects everything the agent learned during the run.

```typescript theme={null}
const AnswerSchema = Assert({
  answer: "string",
  sources: "string[]",
});

const result = await chat.run<typeof AnswerSchema.infer>({
  prompt: "What were this company's last three funding rounds?",
  tools: [ExaSearchTool],
  outputSchema: AnswerSchema,
});
```

<Note>
  Middleware can transform the structured-output call before it is sent — including the JSON Schema handed to the provider — through the `onStructuredOutputConfig` hook. See [Middleware](/ai/agents/middleware#lifecycle-hooks).
</Note>