SurrealDB Database Backend

Configure SurrealDB with its client, URL, credentials, namespace, and database instead of a SQL connection string.

Configure SurrealDB with its client, URL, credentials, namespace, and database instead of a SQL connection string. Local defaults match ./cookbook/scripts/run_surrealdb.sh.

surreal.py
"""
SurrealDB Database Backend
==========================

Configure SurrealDB with its client, URL, credentials, namespace, and database
instead of a SQL connection string. Local defaults match
./cookbook/scripts/run_surrealdb.sh.

Prerequisites: OPENAI_API_KEY, agno[surrealdb], and run_surrealdb.sh
Run: .venvs/demo/bin/python cookbook/05_agent_os/02_databases/surreal.py
Try: Open http://localhost:7777/config and inspect os_database
"""

from os import getenv

from agno.agent import Agent
from agno.db.surrealdb import SurrealDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

# ---------------------------------------------------------------------------
# Create Database
# ---------------------------------------------------------------------------

db = SurrealDb(
    client=None,
    db_url=getenv("SURREALDB_URL", "ws://localhost:8000"),
    db_creds={
        "username": getenv("SURREALDB_USER", "root"),
        "password": getenv("SURREALDB_PASSWORD", "root"),
    },
    db_ns=getenv("SURREALDB_NAMESPACE", "agno"),
    db_db=getenv("SURREALDB_DATABASE", "agent_os"),
    id="agent-os-surreal",
)

# ---------------------------------------------------------------------------
# Create Agent and AgentOS
# ---------------------------------------------------------------------------

surreal_agent = Agent(
    id="surreal-agent",
    name="SurrealDB Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    instructions="Answer questions concisely.",
    markdown=True,
)

agent_os = AgentOS(
    id="surreal-agent-os",
    description="AgentOS backed by SurrealDB.",
    db=db,
    agents=[surreal_agent],
)
app = agent_os.get_app()

# ---------------------------------------------------------------------------
# Run AgentOS
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    agent_os.serve(app="surreal:app", reload=True)

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U "agno[os]" openai surrealdb

Export your OpenAI API key

export OPENAI_API_KEY="your_openai_api_key_here"

Run SurrealDB

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

Run the example

Save the code above as surreal.py, then run:

python surreal.py

Full source: cookbook/05_agent_os/02_databases/surreal.py