# SurrealDB for Agent (/database/providers/surrealdb/usage/surrealdb-for-agent)



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

## Usage [#usage]

Start in a [virtual environment](/sdk/setup).

Install dependencies:

```shell
uv pip install agno sqlalchemy anthropic surrealdb ddgs
```

### Run SurrealDB [#run-surrealdb]

Install [Docker Desktop](https://docs.docker.com/get-started/get-docker/), then start SurrealDB on port `8000`:

```bash
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](https://surrealdb.com/docs/running/docker).

Set your Anthropic API key:

<CodeBlockTabs defaultValue="macOS / Linux">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="macOS / Linux">
      macOS / Linux
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows">
      Windows
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="macOS / Linux">
    ```bash
    export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows">
    ```powershell
    $Env:ANTHROPIC_API_KEY="your_anthropic_api_key_here"
    ```
  </CodeBlockTab>
</CodeBlockTabs>

```python title="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 [#run-the-example]

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

```shell
python surrealdb_for_agent.py
```

## Parameters [#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.                                                                                            |