# Pydantic AI

Pydantic AI is a Python agent framework that brings type-safety and ergonomic API design to generative AI development. The framework applies the same developer experience principles found in FastAPI to building production-grade AI applications.

This guide covers capturing telemetry from Pydantic AI applications using InteractiveAI.

### Prerequisites

* InteractiveAI account with API credentials
* LLM provider credentials (OpenAI, Ollama, or other supported provider)

***

### Installation

```bash
pip install interactiveai pydantic-ai
```

***

### Configuration

Set your API credentials as environment variables:

```python
import os

# InteractiveAI credentials
# Obtain keys from Settings > API Keys in the dashboard
os.environ["INTERACTIVEAI_PUBLIC_KEY"] = "pk-ia-..."
os.environ["INTERACTIVEAI_SECRET_KEY"] = "sk-ia-..."
os.environ["INTERACTIVEAI_HOST"] = "https://app.interactiveai.com"

# Model provider credentials
os.environ["OPENAI_API_KEY"] = "sk-proj-..."
```

Initialize the client and confirm connectivity:

```python
from interactiveai import Interactive

client = Interactive(
    public_key=os.environ["INTERACTIVEAI_PUBLIC_KEY"],
    secret_key=os.environ["INTERACTIVEAI_SECRET_KEY"],
    host=os.environ.get("INTERACTIVEAI_HOST", "https://app.interactiveai.com")
)

if client.auth_check():
    print("Connection established")
else:
    print("Authentication failed - verify credentials")
```

***

### Enabling Trace Capture

Pydantic AI includes built-in instrumentation. Activate it globally:

```python
from pydantic_ai.agent import Agent

Agent.instrument_all()
```

This captures all agent operations and exports OpenTelemetry spans to InteractiveAI.

***

### Running a Pydantic AI Agent

Here's a working example with a tool-equipped agent. Set `instrument=True` when configuring the agent:

```python
from pydantic_ai import Agent, RunContext

quiz_agent = Agent(
    "openai:gpt-4o",
    deps_type=str,
    system_prompt=(
        "Use the `check_answer` function to verify if the "
        "user's answer matches the correct answer provided."
    ),
    instrument=True
)

@quiz_agent.tool
async def check_answer(ctx: RunContext[str], user_answer: str) -> str:
    """Check if the user's answer is correct"""
    correct = ctx.deps.lower()
    return "correct" if user_answer.lower() == correct else "incorrect"

# Run the agent
correct_answer = "paris"
result = await quiz_agent.run("I think the capital of France is Paris", deps=correct_answer)
print(result.output)
```

***

### Enriching Traces with Context

Combine Pydantic AI instrumentation with the InteractiveAI SDK to attach identifiers and metadata:

```python
from interactiveai import Interactive
from pydantic_ai import Agent, RunContext

client = Interactive(
    public_key=os.environ["INTERACTIVEAI_PUBLIC_KEY"],
    secret_key=os.environ["INTERACTIVEAI_SECRET_KEY"],
    host=os.environ.get("INTERACTIVEAI_HOST", "https://app.interactiveai.com")
)

quiz_agent = Agent(
    "openai:gpt-4o",
    deps_type=str,
    system_prompt="Verify answers using the check_answer tool.",
    instrument=True
)

@quiz_agent.tool
async def check_answer(ctx: RunContext[str], user_answer: str) -> str:
    correct = ctx.deps.lower()
    return "correct" if user_answer.lower() == correct else "incorrect"

async def run_with_context():
    with client.start_as_current_span(name="pydantic-ai-quiz") as span:
        
        client.update_current_trace(
            user_id="user",
            session_id="session",
            tags=["pydantic-ai", "quiz"],
            metadata={"category": "geography", "environment": "production"}
        )
        
        query = "The largest ocean is the Pacific"
        correct_answer = "pacific"
        result = await quiz_agent.run(query, deps=correct_answer)
        
        client.update_current_trace(
            input=query,
            output=result.output
        )
        
        return result

    client.flush()

result = await run_with_context()
print(result.output)
```

***

### Trace Visibility

The InteractiveAI dashboard displays:

* Agent execution flow and tool invocations
* LLM calls with prompts and completions
* Tool function arguments and return values
* Token consumption and latency metrics
* Dependency injection context


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.interactive.ai/integrations/ai-frameworks/pydantic-ai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.