> ## 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

<Steps>
  <Step title="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"}
    ```
  </Step>

  <Step title="With Configuration">
    `outputSchema` takes a JSON Schema object. See [Structured Output](/docs/js/structured-output) 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']
      }
    });
    ```
  </Step>
</Steps>

***

## 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"`).
</Tip>

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

<Warning>
  `outputSchema` is an **OpenAI** feature. On a non-OpenAI provider the agent now **warns loudly** and proceeds without structured output — it no longer silently drops the schema.
</Warning>

<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.
</Note>

***

## Output Formats

| Format         | Use Case                                                  |
| -------------- | --------------------------------------------------------- |
| `json`         | Structured data extraction                                |
| `markdown`     | Formatted documents                                       |
| `text`         | Plain text response                                       |
| `outputSchema` | JSON-Schema-constrained output (OpenAI `response_format`) |

***

## API Reference

<Card title="OutputConfig" icon="code" href="/docs/sdk/reference/typescript/classes/OutputConfig">
  Output configuration options
</Card>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use schemas for consistency">
    A JSON Schema ensures the agent returns the same structure every time.
  </Accordion>

  <Accordion title="Keep schemas simple">
    Start with basic types. Deeply nested schemas can confuse some models.
  </Accordion>

  <Accordion title="Mark required fields">
    List the fields you always expect in `required` so they aren't dropped.
  </Accordion>

  <Accordion title="Name your schema">
    Set `outputSchemaName` to label the schema in OpenAI's `response_format` payload. Defaults to `"response"`.
  </Accordion>

  <Accordion title="Use OpenAI for structured output">
    `outputSchema` is OpenAI-native. Non-OpenAI providers warn and answer without the schema — pick an `openai/...` model when you need guaranteed JSON.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Agent" icon="user" href="/docs/js/agent">
    Create agents
  </Card>

  <Card title="Criteria" icon="check-double" href="/docs/js/criteria">
    Validation rules
  </Card>
</CardGroup>