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

# Output

> Control agent response formats

Agents can return structured data in specific formats - JSON, lists, or custom schemas.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Structured Output"
        A[👤 User] --> B[🤖 Agent]
        B --> C[📋 Schema]
        C --> D[📊 Formatted]
    end

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class B agent
    class A,C,D tool
```

## Quick Start

**1. Simple Usage**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Extract contact information as JSON.',
  llm: 'gpt-4o-mini',
  outputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      email: { type: 'string' },
      phone: { type: 'string' }
    },
    required: ['name']
  }
});

const result = await agent.start('John Smith, john@example.com, 555-1234');
// {"name":"John Smith","email":"john@example.com","phone":"555-1234"}
```

**2. With Configuration**

`outputSchema` takes a JSON Schema object. See [Structured Output](https://praison.ai/docs/js/structured-output.md) for the full API.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const agent = new Agent({
  instructions: 'Extract product info',
  llm: 'openai/gpt-4o-mini',
  outputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      price: { type: 'number' },
      inStock: { type: 'boolean' }
    },
    required: ['name', 'price', 'inStock']
  }
});
```

***

## User Interaction Flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Schema
    
    User->>Agent: "Extract data from..."
    Agent->>Schema: Validate format
    Schema-->>Agent: Structured data
    Agent-->>User: {formatted JSON}
```

***

## Schema-Constrained Output

Pass a JSON Schema object to `outputSchema` and the agent returns a JSON string that matches it.

> [!TIP]
>
> As of **v1.7.4**, `outputSchema` is wired through OpenAI's `response_format: json_schema`. The agent sends your schema to the model and returns a JSON string that matches it. Use `outputSchemaName` to name the schema in the request payload (default: `"response"`).

`outputSchema` takes a JSON Schema object (`Record<string, any>`). Pass a full JSON Schema for reliable structured output.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Extract person information from text.',
  llm: 'openai/gpt-4o-mini',
  outputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      age: { type: 'number' },
      city: { type: 'string' }
    },
    required: ['name', 'age', 'city']
  },
  outputSchemaName: 'Person'  // names the schema in the response_format payload
});

const result = await agent.chat('John is 30 years old and lives in Paris');
// '{"name":"John","age":30,"city":"Paris"}'
```

`agent.chat()` returns the raw JSON string — parse it with `JSON.parse(result)`.

***

## Schema-constrained output (`outputSchema`)

`outputSchema` takes a JSON Schema object. When set, the agent sends it to OpenAI as `response_format: { type: 'json_schema', json_schema: { name, schema } }`, so the model is constrained to return matching JSON — the TypeScript parity of Python's `output_json` / `output_pydantic`.

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'Extract product info',
  outputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      price: { type: 'number' },
      inStock: { type: 'boolean' },
    },
    required: ['name', 'price', 'inStock'],
  },
  outputSchemaName: 'product',   // default: "response"
});

const json = await agent.chat('The Widget costs $9.99 and is in stock');
// '{"name":"Widget","price":9.99,"inStock":true}'
```

`outputSchemaName` names the schema in the `response_format` payload (default `"response"`).

> [!NOTE]
>
> `outputSchema` works on **every provider**. OpenAI uses native `response_format: json_schema`; other providers (Anthropic, Google, Groq, Mistral, Ollama, …) go through the AI SDK backend's `generateObject({ schema })`. Cross-provider parity landed in [PraisonAI PR #4412](https://github.com/MervinPraison/PraisonAI/pull/4412).

> [!NOTE]
>
> **Reasoning models omit `temperature`.** `gpt-5*`, `o1*`, `o3*`, and `o4*` reject a non-default temperature with a `400`. The client omits the parameter for these families (the default model is `gpt-5-nano`), so structured output works out of the box — set a temperature explicitly only for non-reasoning models.

***

## Output Formats

| Format | Use Case |
| - | - |
| `json` | Structured data extraction |
| `markdown` | Formatted documents |
| `text` | Plain text response |
| `outputSchema` | JSON-Schema-constrained output (works on every provider) |

***

## API Reference

> [card] [OutputConfig](https://praison.ai/docs/sdk/reference/typescript/classes/OutputConfig.md)
>
> Output configuration options

***

## Best Practices

> [accordion] Use schemas for consistency
>
> A JSON Schema ensures the agent returns the same structure every time.

> [accordion] Keep schemas simple
>
> Start with basic types. Deeply nested schemas can confuse some models.

> [accordion] Mark required fields
>
> List the fields you always expect in `required` so they aren't dropped.

> [accordion] Name your schema
>
> Set `outputSchemaName` to label the schema in OpenAI's `response_format` payload. Defaults to `"response"`.

> [accordion] Works on every provider
>
> `outputSchema` returns matching JSON on every supported provider. Switching the `llm` string from `openai/...` to `anthropic/...` or `google/...` does not change your schema code — see [Structured Output → Provider support](https://praison.ai/docs/js/structured-output.md#provider-support).

***

## Related

> [card] [Agent](https://praison.ai/docs/js/agent.md)
>
> Create agents

> [card] [Criteria](https://praison.ai/docs/js/criteria.md)
>
> Validation rules


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.