Output - PraisonAI

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

Quick Start

Simple Usage

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

With Configuration

outputSchema takes a JSON Schema object. See Structured Output for the full API.

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

Schema-Constrained Output

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

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.

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.

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

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.

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 (OpenAI `response_format`)

API Reference

OutputConfig

Output configuration options

Best Practices

Use schemas for consistency

A JSON Schema ensures the agent returns the same structure every time.

Keep schemas simple

Start with basic types. Deeply nested schemas can confuse some models.

Mark required fields

List the fields you always expect in required so they aren’t dropped.

Name your schema

Set outputSchemaName to label the schema in OpenAI’s response_format payload. Defaults to "response".

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.

Agent

Create agents

Criteria

Validation rules

​Quick Start

​User Interaction Flow

​Schema-Constrained Output

​Schema-constrained output (outputSchema)

​Output Formats

​API Reference

OutputConfig

​Best Practices

​Related

Agent

Criteria

Quick Start

User Interaction Flow

Schema-Constrained Output

Schema-constrained output (`outputSchema`)

Output Formats

API Reference

Best Practices

Related