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

# Pydantic AI

> Run a Pydantic AI agent on Tilde with the trytilde-pydantic-ai adapter.

The Pydantic AI adapter runs a Pydantic AI `Agent` on Tilde. It works with Pydantic AI 2.

<Card title="Example agent" icon="github" href="https://github.com/trytilde/tilde/tree/main/sdk/py/examples/example-agent-pydantic-ai" horizontal>
  A complete Pydantic AI agent with bundled tools, in the Tilde open-source repository.
</Card>

## Install

```bash theme={"system"}
pip install trytilde trytilde-pydantic-ai "pydantic-ai-slim[openai]"
```

## How it works

Pass `tilde_pydantic_ai(ctx)` to each run. It adds a Tilde capability that brings the channel's tools, the agent's Tilde and bundled tools, skill tools, and new user input into the run. It also passes a cancellation token, so stopping the run stops the agent.

```python agent.py theme={"system"}
import tilde
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIResponsesModel
from pydantic_ai.providers.openai import OpenAIProvider
from pydantic_ai.usage import UsageLimits
from tilde_pydantic_ai import convert_to_pydantic_ai_messages, tilde_pydantic_ai

from bundled_tools import TOOLS

INFERENCE = tilde.inference("default")

model = OpenAIResponsesModel(
    "gpt-4o-mini",
    provider=OpenAIProvider(
        base_url=INFERENCE.base_url,
        api_key=INFERENCE.api_key,
        http_client=INFERENCE.async_client(),
    ),
)

responder = Agent(
    model,
    instructions="You are a support assistant. Reply with the channel tools.",
)

async def respond(ctx: tilde.AgentContext) -> None:
    history = await ctx.message.history()
    messages = await convert_to_pydantic_ai_messages(history.items, context=ctx)
    await responder.run(
        message_history=messages,
        usage_limits=UsageLimits(request_limit=8),
        **await tilde_pydantic_ai(ctx, bundled=TOOLS),
    )
```

## Feature compatibility

| Feature | Support | Notes |
| - | - | - |
| Inference gateway | Yes | |
| Framework trace spans | Partial | Tilde records its own spans. The adapter does not turn on Pydantic AI's instrumentation. |
| Tilde and channel tools | Yes | |
| Bundled tools | Partial | Pass `Tool` objects to `define_tools`. Tools registered with `@agent.tool` are not published or recorded. |
| Prompt versioning | Yes | Registers `instructions`, `system_prompt`, and `TemplateStr` templates. Instructions written as a function become a dynamic prompt. |
| Native skills | No | Skills arrive as tools. Pass `skills=False` to `tilde_pydantic_ai` to leave them out. |
| New input during a run | Yes | |

## Limitations

* **Decorated tools.** Pydantic AI keeps `@agent.tool` tools outside the toolset the adapter wraps. `tilde deploy` still lists them, but Tilde cannot record their calls. Use `Tool` objects with `define_tools` instead.
* **Retries.** A tool that raises `ModelRetry` is recorded as a failed call.
* **Private settings.** The adapter reads prompts from fields outside Pydantic AI's public API. It is tested against Pydantic AI 2.43.