# AgentOps

Using SurrealDB Agent Memory in an agent instrumented by AgentOps.

[AgentOps](https://www.agentops.ai/) monitors AI agents: session replay, LLM cost tracking, and tool-call telemetry across most agent frameworks. It is complementary to SurrealDB Agent Memory: AgentOps observes the run; SurrealDB Agent Memory provides the memory. This guide uses both together with the [Python SDK](/docs/agent-memory/integrations/sdks/python.md) (`surrealdb`).

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

## Installation

> [!NOTE]
> This is an integration guide. AgentOps and SurrealDB Agent Memory are separate services; AgentOps instruments the agent, and Agent Memory's calls show up in the captured session.

```bash
pip install agentops openai
pip install --pre surrealdb
```

```bash
export AGENTOPS_API_KEY="..."
export SPECTRON_ENDPOINT="https://api.spectron.example"
export SPECTRON_CONTEXT="acme-prod"
export SPECTRON_API_KEY="sk-spec-..."
```

## Instrument the agent, remember with Agent Memory

`agentops.init()` auto-instruments supported LLM and framework calls. Use the SurrealDB Agent Memory client for recall and storage inside the instrumented run:

```python
import os
import agentops
from openai import OpenAI
from surrealdb import Spectron

agentops.init(os.environ["AGENTOPS_API_KEY"])

llm = OpenAI()
memory = Spectron(
    endpoint=os.environ["SPECTRON_ENDPOINT"],
    context=os.environ["SPECTRON_CONTEXT"],
    api_key=os.environ["SPECTRON_API_KEY"],
)
scope = ["org/acme/user/alice"]

def answer(user_message: str) -> str:
    block = memory.query_context(user_message, k=8, lens=scope)

    completion = llm.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": f"You are a helpful assistant.\n\n## Memory\n{block}"},
            {"role": "user", "content": user_message},
        ],
    )
    reply = completion.choices[0].message.content

    memory.remember_many(
        [{"role": "user", "content": user_message}, {"role": "assistant", "content": reply}],
        scopes=scope,
    )
    return reply
```

The model call is captured in the AgentOps session automatically. To attribute the SurrealDB Agent Memory operations too, wrap them in an AgentOps operation span (`@agentops.operation`) so recall and storage appear in the session timeline.

## Scope per user

Pass a `scope` on every SurrealDB Agent Memory call to isolate memory. A scope is a slash path or an array of paths, for example `["org/acme/user/alice"]`. Register paths with `spectron scopes create` before first use.

## Next steps

- [Python SDK](/docs/agent-memory/integrations/sdks/python.md): the full client surface
- [Agent frameworks](/docs/agent-memory/integrations/frameworks/crewai.md): AgentOps also instruments CrewAI, AutoGen, and others that have first-party SurrealDB Agent Memory adapters