Skip to main content
from praisonaiagents import Agent

agent = Agent(
    name="Calculator",
    instructions="Return only the numeric answer.",
    llm="openai/gpt-4o-mini",
)

agent.start("What is 3 + 3?")
The same agent can run through Pydantic AI when you set framework: pydantic_ai in agents YAML — or use the Agent class directly as above.
Requires praisonai-frameworks 0.1.9+. OpenAI models use OPENAI_API_KEY. Gemini uses GOOGLE_API_KEY or GEMINI_API_KEY.

​
Quick Start

1

Install

pip install "praisonai[pydantic-ai]"
export OPENAI_API_KEY=sk-...
2

Create agents.yaml

framework: pydantic_ai
topic: math
roles:
  calculator:
    role: Calculator
    goal: Compute exactly
    backstory: Return only the numeric answer.
    tasks:
      add:
        description: What is 3 + 3?
        expected_output: "6"
3

Run

praisonai agents.yaml --framework pydantic_ai

​
Models

ModelAPI key
openai/gpt-4o-miniOPENAI_API_KEY
gemini-2.0-flashGOOGLE_API_KEY or GEMINI_API_KEY

​
Supported Patterns

PhasePatternStatus
1Single role, single taskSupported
2Sequential tasks with context:Supported
3handoff.to (single task → delegation tools)Supported

​
Handoffs

Use the same handoff.to pattern as OpenAI Agents — one router role with a single task, specialists without tasks: 
framework: pydantic_ai
topic: language help
roles:
  triage:
    role: Triage Agent
    handoff:
      to:
        - English Agent
    tasks:
      route:
        description: Help with {topic}
  english:
    role: English Agent
    goal: Reply in English only
    backstory: English specialist.
Multi-task configs with handoff.to fall back to sequential execution (OpenAI parity).

​
Migrate from Pydantic AI

praisonai migrate converts Pydantic AI code to PraisonAI automatically.
1

Point migrate at your Pydantic AI project

praisonai migrate ./my-pydantic-ai-app
2

What gets rewritten

Pydantic AIPraisonAI
from pydantic_ai import Agentfrom praisonaiagents import Agent
agent.run_sync("...")agent.start("...")
3

Apply the changes

praisonai migrate ./my-pydantic-ai-app --apply

​
Doctor Check

Run praisonai doctor to confirm the Pydantic AI runtime is picked up. When praisonai[pydantic-ai] is installed, it appears in the runtime table with handoff_support and tool_execution capabilities enabled.
The Pydantic AI runtime card reports:
CapabilityStatus
agent_creation✅ Supported
tool_execution✅ Supported
sequential_execution✅ Supported
handoff_support✅ Supported

​
Limitations

framework: pydantic_ai is only valid in agents YAML. Using it in Workflow YAML raises ValueError: framework='pydantic_ai' in workflow YAML is not supported for workflow execution at load time. Use agents YAML instead.
FeatureStatus
pydantic-graph workflowsNot used
Agent spec YAML bridgeNot supported
Built-in capabilities (WebSearch, Thinking)Not mapped
Workflow YAML with framework: pydantic_aiNot supported — raises ValueError
output_schema / structured depsNot mapped in v1
A2A brokerNot supported

​
Best Practices

Start with a single role and single task to validate your setup before adding complexity.
Add context: to tasks when each step needs output from the previous one.
Keep the router role to a single task with handoff.to; multi-task routers fall back to sequential.
Set OPENAI_API_KEY for openai/ prefixed models and GOOGLE_API_KEY for Gemini models to avoid auth errors.
Use praisonai migrate ./your-app to preview conversion before applying with --apply.

Agno

Run agents YAML through Agno framework

Google ADK

Run agents YAML through Google Agent Development Kit

Code Migration

Migrate existing agent code to PraisonAI

Framework Adapter Plugins

All supported framework adapters