Pydantic Ai Dependency Injection

This shows you how to thread external resources like database connections, API clients, and user context into PydanticAI agents through the RunContext pattern. You define a deps_type dataclass, access it via ctx.deps in your tools and system prompts, then pass the actual dependencies at runtime when you call agent.run(). The type safety is real: Agent[DepsType, OutputType] gives you full static checking across tools, instructions, and run calls. Most useful when your agent needs to hit external services or maintain per-request state like user sessions. The gates section is smart about verifying every ctx.deps access maps to an actual field and your tests don't mock away half the dependencies your tools actually touch.

skills.sh installs: 141
GitHub stars: 87
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add existential-birds/beagle --skill pydantic-ai-dependency-injection --agent claude-code

Installs into .claude/skills of the current project.

Files

PydanticAI Dependency Injection

Core Pattern

Dependencies flow through RunContext:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    db: DatabaseConn
    api_client: HttpClient
    user_id: int

agent = Agent(
    'openai:gpt-4o',
    deps_type=Deps,  # Type for static analysis
)

@agent.tool
async def get_user_balance(ctx: RunContext[Deps]) -> float:
    """Get the current user's account balance."""
    return await ctx.deps.db.get_balance(ctx.deps.user_id)

# At runtime, provide deps
result = await agent.run(
    'What is my balance?',
    deps=Deps(db=db_conn, api_client=client, user_id=123)
)

Defining Dependencies

Use dataclasses or Pydantic models:

from dataclasses import dataclass
from pydantic import BaseModel

# Dataclass (recommended for simplicity)
@dataclass
class Deps:
    db: DatabaseConnection
    cache: CacheClient
    user_context: UserContext

# Pydantic model (if you need validation)
class Deps(BaseModel):
    api_key: str
    endpoint: str
    timeout: int = 30