# SurrealDB for Workflow (/database/providers/surrealdb/usage/surrealdb-for-workflow)



`SurrealDb` stores a Workflow'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_workflow.py"
from agno.agent import Agent
from agno.db.surrealdb import SurrealDb
from agno.models.anthropic import Claude
from agno.team import Team
from agno.tools.hackernews import HackerNewsTools
from agno.tools.websearch import WebSearchTools
from agno.workflow.step import Step
from agno.workflow.workflow import Workflow

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

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,
)

hackernews_agent = Agent(
    name="HackerNews Agent",
    model=Claude(id="claude-sonnet-4-5-20250929"),
    tools=[HackerNewsTools()],
    role="Extract key insights and content from HackerNews posts",
)
web_agent = Agent(
    name="Web Agent",
    model=Claude(id="claude-sonnet-4-5-20250929"),
    tools=[WebSearchTools()],
    role="Search the web for the latest news and trends",
)

research_team = Team(
    name="Research Team",
    model=Claude(id="claude-sonnet-4-5-20250929"),
    members=[hackernews_agent, web_agent],
    instructions="Research tech topics from HackerNews and the web",
)

content_planner = Agent(
    name="Content Planner",
    model=Claude(id="claude-sonnet-4-5-20250929"),
    instructions=[
        "Plan a content schedule over 4 weeks for the provided topic and research content",
        "Ensure that I have posts for 3 posts per week",
    ],
)

research_step = Step(
    name="Research Step",
    team=research_team,
)

content_planning_step = Step(
    name="Content Planning Step",
    agent=content_planner,
)

if __name__ == "__main__":
    content_creation_workflow = Workflow(
        name="Content Creation Workflow",
        description="Automated content creation from blog posts to social media",
        db=db,
        steps=[research_step, content_planning_step],
    )
    content_creation_workflow.print_response(
        input="AI trends in 2024",
        markdown=True,
    )
```

## Run the example [#run-the-example]

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

```shell
python surrealdb_for_workflow.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.                                                                                            |