Pydantic AI 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 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:
pip install pydantic-ai surrealdbexport OPENAI_API_KEY=your-api-keyModels 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.
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:
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.
answer = agent.run_sync('How do I register a function as a custom tool for my agent?')
print(answer.output)