SurrealDB for Agent

SurrealDb stores an Agent's sessions and run history in SurrealDB.

Usage

Install dependencies:

uv pip install agno sqlalchemy anthropic surrealdb ddgs

Run SurrealDB

Install Docker Desktop, then start SurrealDB on port 8000:

docker run --rm --pull always -p 8000:8000 surrealdb/surrealdb:latest start --user root --pass root

This development server uses temporary storage. Its data is lost when the server stops. To retain data across server or container replacement, configure a mounted volume and an on-disk backend as described in the SurrealDB Docker guide.

Set your Anthropic API key:

export ANTHROPIC_API_KEY="your_anthropic_api_key_here"

surrealdb_for_agent.py

from agno.agent import Agent
from agno.db.surrealdb import SurrealDb
from agno.models.anthropic import Claude
from agno.tools.websearch import WebSearchTools

SURREALDB_URL = "ws://localhost:8000"
SURREALDB_USER = "root"
SURREALDB_PASSWORD = "root"
SURREALDB_NAMESPACE = "agno"
SURREALDB_DATABASE = "surrealdb_for_agent"

credentials = {"username": SURREALDB_USER, "password": SURREALDB_PASSWORD}
db = SurrealDb(
    client=None,
    db_url=SURREALDB_URL,
    db_creds=credentials,
    db_ns=SURREALDB_NAMESPACE,
    db_db=SURREALDB_DATABASE,
)

agent = Agent(
    db=db,
    model=Claude(id="claude-sonnet-4-5-20250929"),
    tools=[WebSearchTools()],
    add_history_to_context=True,
)
agent.print_response("How many people live in Costa Rica?")
agent.print_response("What is their national anthem called?")

Run the example

Save the code as surrealdb_for_agent.py, start the database described above, and run:

python surrealdb_for_agent.py

Parameters

Parameter	Type	Default	Description
`id`	`Optional[str]`	-	Database ID. Derived deterministically from `db_url` and `db_db` when omitted.
`client`	`Optional[Union[BlockingWsSurrealConnection, BlockingHttpSurrealConnection]]`	-	A blocking connection, either HTTP or WebSocket.
`db_url`	`str`	-	The SurrealDB connection URL.
`db_creds`	`dict[str, str]`	-	Database credentials dictionary (username, password).
`db_ns`	`str`	-	The SurrealDB namespace to use.
`db_db`	`str`	-	The SurrealDB database name to use.
`session_table`	`Optional[str]`	-	Name of the table to store Agent, Team and Workflow sessions.
`runs_table`	`Optional[str]`	`None`	Storage name for individual runs. Defaults to `agno_runs`, or `<session_table>_runs` when a custom session name is supplied.
`memory_table`	`Optional[str]`	-	Name of the table to store user memories.
`metrics_table`	`Optional[str]`	-	Name of the table to store metrics.
`eval_table`	`Optional[str]`	-	Name of the table to store evaluation runs data.
`knowledge_table`	`Optional[str]`	-	Name of the table to store knowledge documents data.
`traces_table`	`Optional[str]`	-	Name of the table to store traces.
`spans_table`	`Optional[str]`	-	Name of the table to store spans.

Usage

Run SurrealDB

Run the example

Parameters

On this page