Structured AI Agents

Return type-safe, validated outputs from agents using Pydantic models

Structured outputs give agents predictable, validated data. When a Task sets output_pydantic or output_json, PraisonAI fails the task if the model can’t produce a value matching the schema — no silent None.

from praisonaiagents import Agent
from pydantic import BaseModel

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

agent = Agent(name="TopicAgent", llm="gpt-4o-mini")
result = agent.chat("List 3 AI topics", output_pydantic=TopicList)
print(result.topics)

The user asks for structured data; the agent returns validated Pydantic output for downstream code.

Quick Start

1. Simple Usage

   Define a Pydantic model and pass it to output_pydantic:

   from praisonaiagents import Agent
   from pydantic import BaseModel
   
   class AnalysisReport(BaseModel):
       title: str
       findings: str
       summary: str
   
   agent = Agent(
       name="Analyst",
       instructions="Return concise structured analysis.",
   )
   
   result = agent.chat(
       "Summarise recent AI agent trends",
       output_pydantic=AnalysisReport,
   )
   print(result.title, result.summary)

2. Multi-Agent Task

   Use Task with output_pydantic inside an AgentTeam:

   from praisonaiagents import Agent, Task, AgentTeam
   from pydantic import BaseModel
   
   class ResearchReport(BaseModel):
       topic: str
       findings: str
       sources: list[str]
   
   researcher = Agent(
       name="Researcher",
       instructions="Research and return structured findings.",
   )
   
   task = Task(
       description="Research quantum computing developments",
       expected_output="Structured research report",
       agent=researcher,
       output_pydantic=ResearchReport,
   )
   
   team = AgentTeam(agents=[researcher], tasks=[task], process="sequential")
   result = team.start()
   print(result.pydantic.topic)

How It Works

Failure Handling

Structured tasks fail-closed — success is False and error carries the schema name plus the parse error when the model can’t match your schema.

from praisonaiagents import Agent, Task, AgentTeam
from pydantic import BaseModel

class Fact(BaseModel):
    title: str
    detail: str

agent = Agent(name="F", llm="gpt-4o-mini")

task = Task(
    description="Give one fact about the ocean",
    agent=agent,
    output_pydantic=Fact,
    max_retries=2,     # optional — see Task Retry Policy
)

team = AgentTeam(agents=[agent], tasks=[task])
team.start()

# Success — pydantic is guaranteed populated
if task.result.success:
    print(task.result.pydantic.title)
else:
    print("Failed:", task.result.error)   # includes schema name + validation error
    print("Raw text was:", task.result.raw)   # kept for debugging

Pick the option that matches what your downstream code needs:

Native Structured Output

PraisonAI auto-detects models that support native response_format with JSON schema (GPT-4o, Claude 3.5, Gemini 2.0). Unsupported models fall back to prompt injection.

from praisonaiagents import Agent
from pydantic import BaseModel

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

# Auto-detect (default)
agent = Agent(name="TopicAgent", llm="gpt-4o-mini")
result = agent.chat("List 3 AI topics", output_pydantic=TopicList)

# Force native mode
agent = Agent(name="TopicAgent", llm="custom-model", native_structured_output=True)

# Disable native — use text injection fallback
agent = Agent(name="TopicAgent", llm="gpt-4o-mini", native_structured_output=False)

YAML Configuration

framework: praisonai
process: sequential
agents:
  analyst:
    instructions: Expert in data analysis.
    goal: Provide structured insights
    role: Data Analyst
    tasks:
      analysis_task:
        description: Analyse recent AI developments.
        expected_output: Structured analysis report.
        output_structure:
          type: pydantic
          model:
            title: str
            findings: str
            summary: str

Run with praisonai agents.yaml.

Best Practices

Related