> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI with PraisonAI

> Run PraisonAI agents through Pydantic AI via praisonai-frameworks

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](https://github.com/pydantic/pydantic-ai) when you set `framework: pydantic_ai` in agents YAML — or use the `Agent` class directly as above.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Pydantic AI Adapter"
        Y[📄 agents.yaml] --> A[🔀 PraisonAI Router]
        A --> B[🤖 Pydantic AI Agent]
        B --> C[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Y input
    class A,B process
    class C output
```

<Note>
  Requires `praisonai-frameworks` **0.1.9+**. OpenAI models use `OPENAI_API_KEY`. Gemini uses `GOOGLE_API_KEY` or `GEMINI_API_KEY`.
</Note>

## Quick Start

<Steps>
  <Step title="Install">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonai[pydantic-ai]"
    export OPENAI_API_KEY=sk-...
    ```
  </Step>

  <Step title="Create agents.yaml">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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"
    ```
  </Step>

  <Step title="Run">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai agents.yaml --framework pydantic_ai
    ```
  </Step>
</Steps>

## Models

| Model                | API key                              |
| -------------------- | ------------------------------------ |
| `openai/gpt-4o-mini` | `OPENAI_API_KEY`                     |
| `gemini-2.0-flash`   | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |

## Supported Patterns

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Phase Selection"
        P1[Phase 1\nSingle role + task] --> |add context| P2[Phase 2\nSequential tasks]
        P2 --> |add handoff.to| P3[Phase 3\nHandoffs]
    end

    classDef phase fill:#8B0000,stroke:#7C90A0,color:#fff
    class P1,P2,P3 phase
```

| Phase | Pattern                                       | Status    |
| ----- | --------------------------------------------- | --------- |
| 1     | Single role, single task                      | Supported |
| 2     | Sequential tasks with `context:`              | Supported |
| 3     | `handoff.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:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Migration Flow"
        A[🐍 Pydantic AI Code] --> B[⚙️ praisonai migrate]
        B --> C[✅ PraisonAI Agent]
    end

    classDef source fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A source
    class B process
    class C output
```

`praisonai migrate` converts Pydantic AI code to PraisonAI automatically.

<Steps>
  <Step title="Point migrate at your Pydantic AI project">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai migrate ./my-pydantic-ai-app
    ```
  </Step>

  <Step title="What gets rewritten">
    | Pydantic AI                     | PraisonAI                           |
    | ------------------------------- | ----------------------------------- |
    | `from pydantic_ai import Agent` | `from praisonaiagents import Agent` |
    | `agent.run_sync("...")`         | `agent.start("...")`                |
  </Step>

  <Step title="Apply the changes">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai migrate ./my-pydantic-ai-app --apply
    ```
  </Step>
</Steps>

## Doctor Check

<Tip>
  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.
</Tip>

The Pydantic AI runtime card reports:

| Capability             | Status      |
| ---------------------- | ----------- |
| `agent_creation`       | ✅ Supported |
| `tool_execution`       | ✅ Supported |
| `sequential_execution` | ✅ Supported |
| `handoff_support`      | ✅ Supported |

## Limitations

<Warning>
  `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.
</Warning>

| Feature                                     | Status                              |
| ------------------------------------------- | ----------------------------------- |
| pydantic-graph workflows                    | Not used                            |
| Agent spec YAML bridge                      | Not supported                       |
| Built-in capabilities (WebSearch, Thinking) | Not mapped                          |
| Workflow YAML with `framework: pydantic_ai` | Not supported — raises `ValueError` |
| `output_schema` / structured deps           | Not mapped in v1                    |
| A2A broker                                  | Not supported                       |

## Best Practices

<AccordionGroup>
  <Accordion title="Use Phase 1 for simple tasks">
    Start with a single role and single task to validate your setup before adding complexity.
  </Accordion>

  <Accordion title="Use Phase 2 for dependent steps">
    Add `context:` to tasks when each step needs output from the previous one.
  </Accordion>

  <Accordion title="Use Phase 3 for routing">
    Keep the router role to a single task with `handoff.to`; multi-task routers fall back to sequential.
  </Accordion>

  <Accordion title="Match model to API key">
    Set `OPENAI_API_KEY` for `openai/` prefixed models and `GOOGLE_API_KEY` for Gemini models to avoid auth errors.
  </Accordion>

  <Accordion title="Migrate existing Pydantic AI code">
    Use `praisonai migrate ./your-app` to preview conversion before applying with `--apply`.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Agno" icon="robot" href="/docs/framework/agno">
    Run agents YAML through Agno framework
  </Card>

  <Card title="Google ADK" icon="google" href="/docs/framework/google-adk">
    Run agents YAML through Google Agent Development Kit
  </Card>

  <Card title="Code Migration" icon="arrow-right-arrow-left" href="/docs/features/migrate">
    Migrate existing agent code to PraisonAI
  </Card>

  <Card title="Framework Adapter Plugins" icon="plug" href="/docs/features/framework-adapter-plugins">
    All supported framework adapters
  </Card>
</CardGroup>