> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Pydantic AI
> Add HoneyHive observability to your PydanticAI agent applications
[PydanticAI](https://ai.pydantic.dev/) is a Python agent framework from the Pydantic team, built for type-safe LLM applications with dependency injection, structured outputs, and multi-agent support.
HoneyHive integrates with PydanticAI via its native OpenTelemetry support, automatically capturing agent runs, tool calls, and LLM interactions.
## Quick Start
**Add HoneyHive tracing in just 3 lines of code.** Initialize the tracer and call `Agent.instrument_all()`, and all agent runs, tool calls, and model calls are automatically traced.
To see where to initialize the tracer for your environment, including AWS Lambda and long-running servers, see [Tracer Initialization](/v2/tracing/tracer-initialization).
Last tested with `pydantic-ai 1.90.0` (May 2026). Requires PydanticAI 1.x (v3 OTel attributes) -- earlier versions used different span attribute names and tool inputs/outputs will appear empty in the HoneyHive UI.
```bash theme={null}
pip install honeyhive pydantic-ai
```
```python theme={null}
import os
from honeyhive import HoneyHiveTracer
from pydantic_ai import Agent
tracer = HoneyHiveTracer.init(
api_key=os.getenv("HH_API_KEY"),
project=os.getenv("HH_PROJECT"),
)
Agent.instrument_all()
# Your existing PydanticAI code works unchanged
```
## What Gets Traced
The instrumentation automatically captures:
* **Agent runs** - Every agent invocation with inputs and outputs
* **LLM calls** - Model requests, responses, and token usage
* **Tool calls** - Each tool execution with arguments and results
* **Multi-turn conversations** - Message history across turns
* **Streaming** - Streamed responses captured as complete traces
No manual instrumentation required.
***
## Example: Single Agent with Tools
```python theme={null}
import asyncio
import os
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(
api_key=os.getenv("HH_API_KEY"),
project=os.getenv("HH_PROJECT"),
)
Agent.instrument_all()
def lookup_order_status(order_id: str) -> dict:
return {
"ORD-1001": {"state": "shipped", "eta_days": 2},
"ORD-1002": {"state": "processing", "eta_days": 5},
}.get(order_id.upper(), {"state": "not_found"})
@dataclass
class CustomerContext:
customer_name: str
order_id: str
agent = Agent(
"anthropic:claude-haiku-4-5",
name="support_agent",
deps_type=CustomerContext,
instructions=(
"You are a customer support agent. Use check_order to look up "
"order status. Address the customer by name. Keep responses concise."
),
)
@agent.tool
def check_order(ctx: RunContext[CustomerContext], order_id: str) -> str:
"""Look up order status."""
result = lookup_order_status(order_id)
return f"[{ctx.deps.customer_name}] {result}"
async def main():
customer = CustomerContext(customer_name="Alex Kim", order_id="ORD-1002")
await agent.run(
"My order ORD-1002 has been processing for a while. What's the status?",
deps=customer,
)
asyncio.run(main())
```
***
## Example: Multi-Agent Delegation
```python theme={null}
import asyncio
import os
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(
api_key=os.getenv("HH_API_KEY"),
project=os.getenv("HH_PROJECT"),
)
Agent.instrument_all()
@dataclass
class CustomerContext:
customer_name: str
order_id: str
policy_agent = Agent(
"anthropic:claude-haiku-4-5",
name="policy_specialist",
instructions=(
"You are a policy specialist. Give concise answers about "
"refund, cancellation, and shipping policies."
),
)
coordinator = Agent(
"anthropic:claude-haiku-4-5",
name="support_coordinator",
deps_type=CustomerContext,
instructions=(
"You are a support coordinator. For policy questions, "
"delegate to ask_policy_specialist. Combine the answer "
"with any order context to form your response. Be concise."
),
)
@coordinator.tool
async def ask_policy_specialist(
ctx: RunContext[CustomerContext], question: str
) -> str:
"""Delegate policy questions to the specialist."""
result = await policy_agent.run(question, usage=ctx.usage)
return str(result.output)
async def main():
customer = CustomerContext(customer_name="Jordan Lee", order_id="ORD-1003")
await coordinator.run(
"Order ORD-1003 is delayed. Can I cancel and get a refund?",
deps=customer,
)
asyncio.run(main())
```
In HoneyHive, you'll see the full trace hierarchy including coordinator agent, delegated policy specialist calls, and tool executions.
***
## Troubleshooting
### Traces not appearing
1. **Check environment variables** — Ensure `HH_API_KEY` and `HH_PROJECT` are set
2. **Call `instrument_all()` before running agents** — Instrumentation must be active before agent execution:
```python theme={null}
from honeyhive import HoneyHiveTracer
from pydantic_ai import Agent
tracer = HoneyHiveTracer.init(project="your-project")
# ✅ Correct — instrument before running
Agent.instrument_all()
result = await agent.run("Hello")
```
3. **Check your model provider** — Ensure the API key for your chosen model provider is set (e.g., `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
***
## Related
Add user IDs and custom metadata to PydanticAI traces
Create spans for business logic around agent calls
Trace agents across service boundaries
***
## Resources
* [PydanticAI Documentation](https://ai.pydantic.dev/)