Pydantic AI - Tilde documentation

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

Example agent

A complete Pydantic AI agent with bundled tools, in the Tilde open-source repository.

Install

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.

agent.py

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.