pydantic-ai-dependency-injection
This skill shows how to wire external dependencies into PydanticAI agents through RunContext and the deps_type parameter. Learn to define dependencies as dataclasses or Pydantic models, access them safely in tools and instructions, and maintain full type safety across your agent code.
pydantic-ai-dependency-injection teaches you to pass database connections, API clients, and user context to agents via RunContext and deps_type.
AI-generated summary based on this skill's SKILL.md
Install
existential-birds/beagle/pydantic-ai-dependency-injection · repository language: TypeScript
git clone https://github.com/existential-birds/beagle
cp -r beagle/plugins/beagle-ai/skills/pydantic-ai-dependency-injection ~/.claude/skills/pydantic-ai-dependency-injectionFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to use RunContext in PydanticAI?
PydanticAI's RunContext provides access to dependencies through the ctx parameter in your tool functions. Define your dependencies as a dataclass or Pydantic model, set deps_type on your Agent, then pass an instance via agent.run(deps=your_deps). Inside tools, retrieve them with ctx.deps to access database connections, API clients, or other resources safely and with full type checking.
What is deps_type in pydantic-ai-dependency-injection?
The deps_type parameter on Agent[DepsType, OutputType] specifies the type of dependencies your agent accepts. It enables generic type safety: define a dataclass with your resources (database, logger, API client), pass deps_type=YourDepsClass to Agent(), then PydanticAI enforces that only matching dependency instances reach your tools and instructions.
How do I pass a database connection to a PydanticAI agent?
Create a dataclass holding your database connection, set it as deps_type on your Agent, then pass an instance to agent.run(deps=db_deps). In your tool functions, access it via ctx.deps.db_connection. This pattern works for any external resource—API clients, loggers, configuration—keeping them injectable and testable.
How can pydantic-ai-dependency-injection achieve type safety?
Use the generic Agent[DepsType, OutputType] pattern: define deps_type with a strongly-typed dataclass or Pydantic model, and PydanticAI validates at runtime that dependencies match. Your IDE and type checker see ctx.deps as the exact type you declared, eliminating runtime surprises and enabling autocomplete on injected resources.
How do I mock and override dependencies for testing?
Create a test version of your deps dataclass with mock objects (mock database, stub API client), then pass it to agent.run(deps=test_deps) in your test. Since deps_type is generic, you can swap implementations without changing agent code, making unit tests fast and isolated.
What's the difference between accessing ctx.deps vs passing deps directly?
PydanticAI's RunContext pattern (ctx.deps) decouples tools from initialization logic: dependencies are bound once at agent.run() time and available to all tools without threading parameters through function signatures. This keeps tool code clean and enables consistent, type-safe access across your entire agent workflow.
SKILL.md
rendered from the published skill — quoted content, verbatim
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:
```python from dataclasses import dataclass from pydantic import BaseModel
Dataclass (recommended for simplicity)
@dataclass class Deps: db: DatabaseConnection cache: CacheClient user_context:
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
plugins/beagle-ai/skills/pydantic-ai-dependency-injection/SKILL.md