Prerequisites

  • Python 3.10 or higher
  • PraisonAI Agents package installed
  • Basic understanding of Python and Pydantic

​
Quick Start

Create AI agents that return structured, validated outputs in just a few lines of code!

1

Install Package

First, install the PraisonAI Agents package:

pip install praisonaiagents
2

Import Required Components

Import the necessary components:

from praisonaiagents import Agent, Task, PraisonAIAgents, Tools
from pydantic import BaseModel
3

Define Your Data Model

Create a Pydantic model to define your output structure:

class AnalysisReport(BaseModel):
    title: str
    findings: str
    summary: str
4

Create Structured Tasks

Create tasks with structured outputs:

research_task = Task(
    description="Research recent AI developments",
    agent=researcher,
    expected_output="Research findings"
)

analysis_task = Task(
    description="Analyze research findings",
    agent=analyst,
    output_pydantic=AnalysisReport,  # For Pydantic output
    # or output_json=AnalysisReport  # For JSON output
    expected_output="Structured analysis report"
)

​
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

​
Key Components

Pydantic Models

Define your data structure

class ResearchReport(BaseModel):
    title: str
    content: str

Task Configuration

Configure output format

Task(output_pydantic=Model)
# or
Task(output_json=Model)

Output Validation

Automatic validation of responses against your model

Format Options

Choose between Pydantic objects or JSON output

​
Output Types

Pydantic Output

task = Task(
    output_pydantic=AnalysisReport
)
# Returns Pydantic object

Get type-safe Pydantic model instances

JSON Output

task = Task(
    output_json=AnalysisReport
)
# Returns JSON dict

Get JSON dictionary matching model schema

​
Examples

​
Research Analysis with Structured Output

from praisonaiagents import Agent, Task, PraisonAIAgents, Tools
from pydantic import BaseModel

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

# Create agents
researcher = Agent(
    name="AIResearcher",
    role="Technology Research Analyst",
    tools=[Tools.internet_search]
)

analyst = Agent(
    name="DataAnalyst",
    role="Data Insights Specialist"
)

# Define structured tasks
research_task = Task(
    name="gather_research",
    description="Research recent AI developments in 2024",
    agent=researcher,
    expected_output="Research findings"
)

analysis_task = Task(
    name="analyze_findings",
    description="Analyze research findings and create structured report",
    agent=analyst,
    output_pydantic=AnalysisReport,
    expected_output="Structured analysis report"
)

# Initialize and run agents
agents = PraisonAIAgents(
    agents=[researcher, analyst],
    tasks=[research_task, analysis_task]
)
result = agents.start()

​
Different Output Formats

​
Best Practices

​
Common Patterns

​
Research and Structured Analysis

class ResearchReport(BaseModel):
    topic: str
    findings: str
    sources: list[str]

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

research_task = Task(
    description="Research quantum computing",
    agent=researcher,
    output_pydantic=ResearchReport
)

analysis_task = Task(
    description="Analyze research implications",
    agent=analyst,
    output_pydantic=Analysis
)

​
Data Collection and Summary

class DataPoint(BaseModel):
    timestamp: str
    value: float
    source: str

class Summary(BaseModel):
    average: float
    trends: str
    insights: str

collection_task = Task(
    description="Collect data points",
    output_pydantic=DataPoint
)

summary_task = Task(
    description="Summarize data",
    output_pydantic=Summary
)

​
Troubleshooting

Validation Errors

Check if your model matches the expected output structure

# Print model schema
print(Model.schema_json())

Output Format

Verify you’re accessing the right output field:

  • result.pydantic for Pydantic
  • result.json_dict for JSON

​
Next Steps

Advanced Models

Learn about advanced Pydantic model configurations

Custom Validation

Add custom validation to your models

Structured outputs make your AI agents more reliable and their responses more predictable. They’re perfect for production systems where data consistency is crucial.

Was this page helpful?

Math AgentCallbacks