Skip to main content

​
Quick Start

1

Install Package

First, install the PraisonAI Agents package:
pip install praisonaiagents
2

Set API Key

Set your OpenAI API key as an environment variable in your terminal:
export OPENAI_API_KEY=your_api_key_here
3

Create a file

Create a new file app.py with the basic setup:
from praisonaiagents import Agent, Task, AgentTeam, Tools
from pydantic import BaseModel

# Define your data structure
class AnalysisReport(BaseModel):
    title: str
    findings: str
    summary: str

# Create agent
analyst = Agent(
    role="Data Analyst",
    goal="Analyze data and provide structured insights",
    backstory="Expert in data analysis and insights generation",
    tools=[Tools.internet_search],
    
)

# Create task with structured output
task = Task(
    description="Analyze recent AI developments",
    expected_output="Structured analysis report",
    agent=analyst,
    output_pydantic=AnalysisReport
)

# Create and start the agents
agents = AgentTeam(
    agents=[analyst],
    tasks=[task],
    process="sequential",
    verbose=2
)

# Start execution
result = agents.start()
print(result.pydantic.title)
print(result.pydantic.findings)
print(result.pydantic.summary)
4

Start Agents

Type this in your terminal to run your agents:
python app.py
Requirements
  • Python 3.10 or higher
  • OpenAI API key. Generate OpenAI API key here. Use Other models using this guide.
  • Basic understanding of Python and Pydantic

​
Understanding Structured Outputs

What are Structured Outputs?

Structured outputs allow you to:
  • Define exact shape of data using Pydantic models
  • Get type-safe, validated responses
  • Choose between Pydantic objects or JSON
  • Ensure consistent output format across agent responses

​
Features

Pydantic Models

Define exact data structures with validation.

JSON Output

Get structured JSON responses.

Type Safety

Ensure type-safe, validated outputs.

Format Options

Choose between Pydantic or JSON.

​
Native Structured Output

PraisonAI automatically uses native response_format with JSON schema for models that support it (like GPT-4o, Claude 3.5, Gemini 2.0). This ensures clean JSON outputs without schema echoing.
By default, PraisonAI auto-detects if your model supports native structured output:
from praisonaiagents import Agent
from pydantic import BaseModel
from typing import List

class TopicList(BaseModel):
    topics: List[str]

# Auto-detects gpt-4o-mini supports native structured output
agent = Agent(
    name="TopicAgent",
    llm="gpt-4o-mini"
)

result = agent.chat("List 3 AI topics", output_pydantic=TopicList)
Supported Models: GPT-4o, GPT-4o-mini, Claude 3.5 Sonnet, Gemini 2.0 Flash, and other models that support OpenAI’s response_format with json_schema.Flow:
  1. Agent checks if model supports native structured output
  2. If supported → uses response_format with JSON schema (clean output)
  3. If not supported → falls back to prompt injection (schema in prompt)

​
Multi-Agent Structured Analysis

1

Install Package

First, install the PraisonAI Agents package:
pip install praisonaiagents
2

Set API Key

Set your OpenAI API key as an environment variable in your terminal:
export OPENAI_API_KEY=your_api_key_here
3

Create a file

Create a new file app.py with the basic setup:
from praisonaiagents import Agent, Task, AgentTeam, Tools
from pydantic import BaseModel

# Define output structures
class ResearchReport(BaseModel):
    topic: str
    findings: str
    sources: list[str]

class Analysis(BaseModel):
    key_points: list[str]
    implications: str
    recommendations: str

# Create first agent for research
researcher = Agent(
    role="Research Analyst",
    goal="Gather and structure research data",
    backstory="Expert in research and data collection",
    tools=[Tools.internet_search],
    
)

# Create second agent for analysis
analyst = Agent(
    role="Data Analyst",
    goal="Analyze research and provide structured insights",
    backstory="Expert in data analysis and insights generation",
    
)

# Create first task
research_task = Task(
    description="Research quantum computing developments",
    expected_output="Structured research findings",
    agent=researcher,
    output_pydantic=ResearchReport
)

# Create second task
analysis_task = Task(
    description="Analyze research implications",
    expected_output="Structured analysis report",
    agent=analyst,
    output_pydantic=Analysis
)

# Create and start the agents
agents = AgentTeam(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task],
    process="sequential"
)

# Start execution
result = agents.start()
4

Start Agents

Type this in your terminal to run your agents:
python app.py

​
Configuration Options

# Create an agent with structured output configuration
agent = Agent(
    role="Data Analyst",
    goal="Provide structured analysis",
    backstory="Expert in data analysis",
    tools=[Tools.internet_search],
      # Enable detailed logging
    llm="gpt-4o"  # Language model to use
)

# Task with Pydantic output
task = Task(
    description="Analyze data",
    expected_output="Structured report",
    agent=agent,
    output_pydantic=AnalysisReport  # Use Pydantic model
    # or output_json=AnalysisReport  # Use JSON output
)

​
Troubleshooting

Validation Errors

If model validation fails:
  • Check data types match model
  • Verify required fields
  • Enable verbose mode for debugging

Output Format

If output format is incorrect:
  • Verify model definition
  • Check output_pydantic vs output_json
  • Review field specifications

​
Next Steps

AutoAgents

Learn about automatically created and managed AI agents

Mini Agents

Explore lightweight, focused AI agents
For optimal results, ensure your Pydantic models accurately represent your desired output structure.