Output

Control agent response formats

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

Quick Start

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

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

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

Output Formats

API Reference

Best Practices

Related