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

# Pydantic

> Integrate Snow Leopard with Pydantic AI agents for structured data retrieval.

This guide shows you how to add Snow Leopard data retrieval to a [Pydantic](https://pydantic.dev/) [AI](https://ai.pydantic.dev/) agent.

## Prerequisites

* Python 3.10+
* [uv](https://docs.astral.sh/uv/) package manager
* Anthropic API key (or another [supported model provider](https://ai.pydantic.dev/models/))
* [Snow Leopard Cloud API key](/cloud/getting-started#api-keys)
* A [Snow Leopard Cloud](/cloud/getting-started) instance with at least one [data source](/cloud/getting-started#adding-a-data-source) connected
* Your instance ID, from the instance's [Connection Info](/cloud/getting-started#connection-info) tab

<Note>
  Don't have data? Load the [sample Northwind dataset](https://github.com/SnowLeopard-AI/northwind_psql) into a PostgreSQL database that Snow Leopard Cloud can reach, such as a hosted [Neon](https://neon.com) or [Supabase](https://supabase.com) database. Run the dataset's `northwind.sql` script against your database, then [add the database as a data source](/cloud/getting-started#adding-a-data-source) in your instance.
</Note>

## Start from scratch

Clone and run the [complete working example](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/pydantic-ai):

```bash theme={null}
git clone https://github.com/SnowLeopard-AI/snowy-examples.git
cd snowy-examples/quickstart/pydantic-ai
```

Set your environment variables:

```bash theme={null}
export ANTHROPIC_API_KEY=your-anthropic-key
export SNOWLEOPARD_API_KEY=your-snowleopard-key
export SNOWLEOPARD_INSTANCE_ID=your-instance-id
```

Run the agent:

```bash theme={null}
uv run clai --agent agent:agent
```

You now have an interactive REPL where you can ask questions about your data:

```
clai ➤ How many customers do we have?
```

## Bring your own agent

Already have a Pydantic AI agent? Add Snow Leopard data retrieval with these steps.

### 1. Install dependencies

```bash theme={null}
uv add snowleopard
```

### 2. Create the Snow Leopard tool

Add a tool to your agent that calls Snow Leopard to retrieve data:

```python theme={null}
from pydantic_ai import Agent, RunContext
from snowleopard import SnowLeopardClient

# Your existing agent
agent = Agent(
    'anthropic:claude-sonnet-4-5',
    instructions='Be concise, reply with one sentence.',
)

# Initialize the Snow Leopard client
snowy = SnowLeopardClient(api_key="{your-snowleopard-api-key}")

# Add the data retrieval tool
@agent.tool
def get_data(ctx: RunContext[str], user_query: str) -> str:
    """
    Retrieve data from the database.
    Describe your data here - this becomes part of the agent's context.
    """
    response = snowy.retrieve(user_query=user_query, instance_id="{your-instance-id}")
    return str(response)
```

### 3. Customize the tool description

The tool's docstring tells the agent when and how to use it. Update it to describe your specific data:

```python theme={null}
@agent.tool
def get_data(ctx: RunContext[str], user_query: str) -> str:
    """
    Retrieve customer order data.
    Contains order history, products, and customer information.
    Use this to answer questions about sales, orders, and customers.
    """
    response = snowy.retrieve(user_query=user_query, instance_id="{your-instance-id}")
    return str(response)
```

## Next steps

* View the [full example on GitHub](https://github.com/SnowLeopard-AI/snowy-examples/tree/main/quickstart/pydantic-ai)
* See our full [API documentation](https://docs.snowleopard.ai/) to learn about the [Retrieve](/cloud/endpoints/retrieve) and [Response](/cloud/endpoints/response) endpoints
* Improve accuracy by giving Snow Leopard [feedback](/cloud/endpoints/feedback) about your business logic and terminology
* See this quickstart in action with the [Data Agent recipe](/recipes/copilotkit-data-agent)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.