AgentOps | Observability

AgentOps 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 (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.

pip install agentops openai
pip install --pre surrealdb

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:

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: the full client surface
Agent frameworks: AgentOps also instruments CrewAI, AutoGen, and others that have first-party SurrealDB Agent Memory adapters