---
title: "Pydantic AI"
description: "This section contains information about the Pydantic AI framework and how to integrate it with SurrealDB."
canonical_url: "https://surrealdb.com/docs/integrate/integrations/ai-frameworks/pydantic-ai"
section: "AI frameworks"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Pydantic AI

This section contains information about the Pydantic AI framework and how to integrate it with SurrealDB.

[Pydantic AI](https://ai.pydantic.dev) is a Python agent framework for building production-grade applications and workflows with Generative AI.

A Pydantic AI agent uses SurrealDB as its knowledge store through a tool: a function that the agent's model can call. The tool takes the model's search text, embeds it with the same model that embedded the stored records, runs a SurrealDB vector search, and returns the nearest records as text. This page shows those parts. The tutorial [Build an AI agent with Python](/docs/learn/tutorials/tutorials/build-an-ai-agent.md#getting-started-with-pydantic-ai) has the complete retrieval-augmented generation (RAG) program, which builds a search database from the Logfire documentation, and the commands that run it.

## Install

The example uses the Pydantic AI and SurrealDB Python packages, and an OpenAI API key for the embedding and chat models:

```bash
pip install pydantic-ai surrealdb
```

**Bash**

```bash
export OPENAI_API_KEY=your-api-key
```

**PowerShell**

```powershell
$env:OPENAI_API_KEY = "your-api-key"
```

## Models and the retrieval tool

An `Embedder` turns text into vectors and an `Agent` holds the chat model. The `@agent.tool_plain` decorator registers `retrieve()` as a tool, and its docstring tells the model what the tool does and what its argument means. This is the tool from the tutorial's program without its Logfire tracing.

```python
from pydantic_ai import Agent, Embedder

embedder = Embedder('openai:text-embedding-3-small')
agent = Agent('openai:gpt-5.2')


@agent.tool_plain
async def retrieve(search_query: str) -> str:
    """Retrieve documentation sections based on a search query.

    Args:
        search_query: The search query.
    """
    result = await embedder.embed_query(search_query)
    embedding_vector = result.embeddings[0]

    # SurrealDB vector search using the HNSW index
    async with database_connect(False) as db:
        rows = await query(
            db,
            """
            SELECT url, title, content, vector::distance::knn() AS dist
            FROM doc_sections
            WHERE embedding <|8, 40|> $vector
            ORDER BY dist ASC
            """,
            {'vector': list(embedding_vector)},
            RetrievalQueryResult,
        )

    return '\n\n'.join(
        f'# {row.title}\nDocumentation URL:{row.url}\n\n{row.content}' for row in rows
    )
```

`database_connect()` opens a connection to SurrealDB, embedded in a local file or to a server at a URL, and `query()` validates the records it returns as `RetrievalQueryResult` models. Both are defined in the full program in the tutorial.

The `<|8, 40|>` operator asks the HNSW index for the 8 nearest records, with 40 as the size of the candidate list it searches. `vector::distance::knn()` returns the distance that the operator already computed for each record.

## Schema

The vector index must have the dimension of the embedding model, which is 1536 for `text-embedding-3-small`:

```surql
DEFINE TABLE doc_sections SCHEMALESS;
DEFINE FIELD embedding ON doc_sections TYPE array<float>;
DEFINE INDEX hnsw_idx_doc_sections ON doc_sections
    FIELDS embedding HNSW DIMENSION 1536 DIST COSINE;
```

To use another embedding model, change the `Embedder` model string and the `DIMENSION` together. The records already stored must also be embedded again, because vectors from two different models cannot be compared.

## Run the agent

`agent.run_sync()` sends a question to the model, which calls `retrieve()` as often as it needs before it writes its answer. In async code, `await agent.run()` does the same. `agent.to_web()` returns a web chat application for the same agent.

```python
answer = agent.run_sync('How do I register a function as a custom tool for my agent?')
print(answer.output)
```
