OpenAI Agents SDK

Spectron gives agents built with the OpenAI Agents SDK a durable, shared memory. An agent can remember across runs, recall what it needs before answering, and share memory with other agents through a common scope.

Package: spectron-openai-agents (PyPI). Memory works two ways, and they compose: function tools the agent calls itself, and automatic memory wrapped around a run.

Installation

pip install spectron-openai-agents

Environment

export OPENAI_API_KEY="your-openai-api-key"
export SPECTRON_URL="https://your-spectron-endpoint"
export SPECTRON_NAMESPACE="your-namespace"
export SPECTRON_DATABASE="your-database"
export SPECTRON_TOKEN="your-token"   # optional for local, unsecured instances

Memory as function tools

The agent decides when to remember, recall, context, reflect, or forget. get_spectron_tools builds the tools from the SPECTRON_* environment by default; pass client= for an explicit SpectronClient or include= to expose a subset:

from agents import Agent, Runner
from spectron_openai_agents import get_spectron_tools

agent = Agent(
    name="assistant",
    instructions=(
        "You are a helpful assistant. Use recall to check memory before you "
        "answer, and use remember to store anything worth keeping."
    ),
    tools=get_spectron_tools(session_id="user-123"),
)

Runner.run_sync(agent, "My name is Ada and I work on databases.")

result = Runner.run_sync(agent, "What do you know about me?")
print(result.final_output)

Automatic memory around a run

run_with_memory recalls memory relevant to the input, injects it into the prompt, runs the agent, and stores the result. The agent needs no memory tools of its own:

import asyncio
from agents import Agent
from spectron_openai_agents import MemoryScope, run_with_memory

agent = Agent(name="assistant", instructions="You are a helpful assistant.")
scope = MemoryScope(session_id="user-123")

async def main():
    await run_with_memory(agent, "My name is Ada.", scope=scope)

    result = await run_with_memory(agent, "What is my name?", scope=scope)
    print(result.final_output)

asyncio.run(main())

Persisting output with hooks

To save an agent's output while running it yourself, attach SpectronMemoryHooks:

from agents import Runner
from spectron_openai_agents import SpectronClient, SpectronMemoryHooks, MemoryScope

client = SpectronClient.from_env()
hooks = SpectronMemoryHooks(client, MemoryScope(session_id="user-123"))

await Runner.run(agent, "Summarize our project decisions.", hooks=hooks)

Multi-agent shared memory

Both approaches talk to Spectron through a single SpectronClient, scoped by a MemoryScope (agent_id, session_id, user_id). Agents that share a MemoryScope read and write the same memory, so what one agent stores is available to another.

When to use MCP or the SDK instead

For an MCP-native host, use the MCP server.
To call Spectron directly, use the Python SDK.