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

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

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

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.

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