> ## Documentation Index
> Fetch the complete documentation index at: https://www.adaline.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI

> Observe Pydantic AI agents with Adaline.

# Pydantic AI

Use the Adaline Pydantic AI integration to observe agent runs in Adaline without rewriting your agent logic. The integration wraps an existing Pydantic AI agent and instruments its run lifecycle.

## Prerequisites

Before you start, make sure you have:

* An [Adaline account](https://app.adaline.ai/sign-up?utm_source=adaline.ai).
* A **workspace API key** — create one under **Settings → API keys**.
* Your **project ID** — copy it from **Monitor → Copy Project ID**.

See [Integrate your AI Agent](/get-started/integrate-your-ai-agent) for a full walkthrough.

Set both as environment variables before running the examples on this page:

```bash theme={null}
export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"
```

## Install

```bash theme={null}
pip install adaline-client adaline-pydantic-ai pydantic-ai
```

Install Pydantic AI itself alongside the Adaline integration package.

## Initialize Adaline

Create an Adaline client, then initialize a monitor for the target project.

```python theme={null}
import os

from adaline import Adaline

adaline = Adaline(api_key=os.environ["ADALINE_API_KEY"])
monitor = adaline.init_monitor(project_id=os.environ["ADALINE_PROJECT_ID"])
```

<Note>
  For production guidance — buffering, batching, retries, serverless flushing, and graceful shutdown — see [Instrument with the Adaline SDK](/instrument/with-adaline-sdks).
</Note>

## Wrap an existing agent

Wrap an existing `pydantic_ai.Agent` using `instrument_pydantic_ai_agent`.

```python theme={null}
from pydantic_ai import Agent

from adaline_pydantic_ai import instrument_pydantic_ai_agent

agent = Agent(
    "openai:gpt-4o-mini",
    system_prompt="Reply with exactly one word: 'hello'.",
)

wrapped = instrument_pydantic_ai_agent(
    agent,
    monitor=monitor,
)
```

## Basic example

This example keeps the integration intentionally small: one wrapped Pydantic AI agent run.

```python theme={null}
import asyncio
from pydantic_ai import Agent

from adaline_pydantic_ai import instrument_pydantic_ai_agent

async def main():
    parent_trace = monitor.log_trace(
        name="pydantic-ai-run",
        reference_id="pydantic-ai-run-1",
    )

    agent = Agent(
        "openai:gpt-4o-mini",
        system_prompt="Reply with exactly one word: 'hello'.",
    )

    wrapped = instrument_pydantic_ai_agent(
        agent,
        monitor=monitor,
        session_id="pydantic-ai-session",
        parent_trace=parent_trace,
        tags=["pydantic-ai"],
    )

    result = await wrapped.run("Say hello.")

    parent_trace.end()
    await monitor.flush()


asyncio.run(main())
```

## Alternative entrypoint

If you prefer to construct the wrapper directly, the package also exports `AdalinePydanticAIWrapperAgent`.

```python theme={null}
from adaline_pydantic_ai import AdalinePydanticAIWrapperAgent

wrapped = AdalinePydanticAIWrapperAgent(
    agent,
    monitor=monitor,
    session_id="pydantic-ai-session",
    tags=["pydantic-ai"],
)
```

## Use an existing parent trace or span

The wrapper accepts:

* `parent_trace`
* `parent_span`

Pass one or the other, but not both.

## What the wrapper captures

The Pydantic AI integration is designed to capture agent run activity, including:

* the wrapped agent run root
* model/provider metadata emitted during the run
* input and output payloads for the observed operation
* child spans under an Adaline parent when provided

This page focuses on how to wrap the agent. The exact span tree depends on the events and model interactions your agent emits.

## Next steps

<CardGroup cols={2}>
  <Card title="Instrument with the Adaline SDK" icon="code" href="/instrument/with-adaline-sdks">
    Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.
  </Card>

  <Card title="SDK reference" icon="braces" href="/reference/sdk/v2/overview">
    Full class and type reference for the TypeScript and Python SDKs.
  </Card>

  <Card title="All integrations" icon="layout-grid" href="/integrations/introduction">
    Browse every framework and AI-provider integration Adaline supports.
  </Card>

  <Card title="View your logs" icon="line-chart" href="https://app.adaline.ai">
    Open Adaline to see traces and spans land in your project.
  </Card>
</CardGroup>