Structured AI Agents

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

Structured outputs give agents predictable, validated data — ideal for APIs, dashboards, and downstream automation.

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

Phase	What happens
1. Request	You pass a Pydantic model to output_pydantic
2. Generate	The agent produces a response
3. Validate	The response is checked against your schema
4. Return	A typed object flows back to your code

---

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)

Option	Type	Default	Description
output_pydantic	BaseModel	None	Return a validated Pydantic object
output_json	BaseModel	None	Return structured JSON (same schema)
native_structured_output	bool	auto	Force native response_format on/off

---

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

Keep models small and explicit

Define only the fields you need. Smaller schemas validate faster and reduce model confusion.

Prefer output_pydantic for Python apps

Use output_pydantic when you want a typed object; use output_json when you only need serialisable dicts.

Let native mode auto-detect

Leave native_structured_output unset unless you know your model needs forcing — the SDK picks the cleanest path.

Validate failures in verbose mode

Enable verbose output while tuning schemas so validation errors show which field failed.

---

Related

Structured LLM Errors

Handle validation and LLM failures gracefully

Output & Display

Format and present agent responses

Agent Teams

Multi-agent workflows with structured tasks

Tasks

Task configuration and output options