Skip to content

The SDKs keep an OpenAI Agents SDK session's history in Loom - #737

Open
zlareb1 wants to merge 1 commit into
mainfrom
feat/sdk-openai-agents-session
Open

zlareb1 wants to merge 1 commit into
mainfrom
feat/sdk-openai-agents-session

Conversation

@zlareb1

@zlareb1 zlareb1 commented Nov 16, 2026

Copy link
Copy Markdown
Member

Related: #650 (the OpenAI Agents SDK tools this sits next to)

Changelog category (leave one):

  • New Feature

Changelog entry (one or two sentences a user of Loom can read without the diff; the release pull request collects these into the release notes):

The Python and TypeScript SDKs ship LoomSession, the OpenAI Agents SDK's Session over Loom: a run's conversation history lives in Loom, so every process and both SDKs that open the same session for the same user read the same history.

Why

The OpenAI Agents SDK keeps a run's conversation history in a Session (get_items, add_items, pop_item, clear_session); its own implementations are a local SQLite file, Redis and OpenAI's hosted conversations. With Loom's tools (#650) a model keeps long-term memory in Loom, but the history itself stayed in one of those stores; the frameworks page said Loom could not hold it because Loom's conversations are append-only. This PR implements the session over Loom's memory rows, which do support removal, so the history lives in the user's Loom deployment next to their memories. No store, vector database or cache is added.

Design (interfaces read from openai-agents 0.24.0 and @openai/agents 0.22.0):

  • The Session protocol, not SessionABC. The SDK's docstring asks third-party libraries to implement the protocol. LoomSession has session_id, session_settings and the four async methods; the TypeScript class implements Session (getSessionId, getItems, addItems, popItem, clearSession).
  • Items are episodic memories. Each item is one memory.set of type episodic under <key_prefix>/<20-digit nanoseconds>-<8 random hex>, its JSON the value. An episodic memory is not embedded, so it is never merged with or judged against another row (checked against a running server: three identical items under three keys answer with no verdict and stay three rows); the timestamp keys sort in the order items were added, and the random suffix keeps two writers apart. memory.bulk_set is not used: a batch folds a value byte-identical to a live row of the same user, and a conversation repeats items.
  • Session. The rows carry the user and a Loom session derived from the pair, oai-<first 20 hex of sha256 of the compact JSON [user, session id]> (Loom files a long value's chunks by session alone, and a caller chooses its ids; The Python SDK ships a Google ADK memory service #696 found this for ADK). Both SDKs hash the same compact JSON, so a Python and a TypeScript LoomSession of the same id and user read the same rows (a test in each pins the same digest).
  • get_items lists the session's rows (memory.list with prefix, memory_type="episodic", fields=["memory_key", "value"], paged by offset while truncated) and keeps the latest limit, or session_settings.limit (resolve_session_limit, as the SDK's own sessions do). pop_item deletes and returns the last row; clear_session deletes every row of the session; both use memory.delete under the user and session, so another user's or session's history is untouched.
  • user_id unset writes the namespace's shared rows; an empty or - user, an empty session id and an empty key prefix are refused.
  • The docs replace the paragraph that sent history to another store.

Scope and risk

SDK-only: two classes in the existing OpenAI Agents modules (no new extra or peer dependency), docs. No server, wire or schema change; episodic memories are covered by erasure like every memory row. uv.lock and package-lock.json are unchanged.

Compatibility, rollout and rollback

  • Wire: none.
  • Operator steps: none.
  • Rollback: reverting removes the classes.

Tests

  • sdk/python/tests/test_openai_agents.py through make test-sdk-adapter-openai-agents (17 tests, 7 new; mypy --strict): items keep their order across list pages, with a repeated item kept twice, written as episodic rows of the user and the derived session; get_items(limit), limit=0 and session_settings.limit; pop_item returns and removes the latest, None when empty; clear_session deletes only its own session's rows, not another session's or another user's; the derived session is per user, unambiguous and equal to the TypeScript one; the refusals; a real Runner with a scripted model reads the first run's history in the second run and extends it.
  • The same tests pass with SDK_ADAPTERS_RESOLUTION=lowest-direct on Python 3.11 (openai-agents 0.24.0).
  • sdk/typescript/src/integrations/openai-agents.test.ts (4 new, through a real Agent over a fetch stub): the same order, paging, repeats, episodic rows, pop, clear, refusals and the shared digest. The TS SDK's gates: biome check, tsc --noEmit, vitest run (353 passed), check:readme, check:dist (the dist exports test now lists LoomSession).
  • tests/integration/test_sdk_openai_agents_session.py against a local server: items added, read back as written (as episodic rows of the user and session), invisible to another user, popped, limited and cleared. 1 passed with openai-agents installed; without it the module skips, as in CI's integration jobs.
  • make format lint; the unit tests that name the integrations, the extras, the framework docs, doc links and public copy (990 passed).

AI assistance in the code (leave one; writing this description with AI is fine):

  • AI-generated (an agent wrote most of the diff): Claude Code. Checked: Session, SessionABC, SQLiteSession and resolve_session_limit in openai-agents 0.24.0 and the Session interface in @openai/agents-core, runs through the SDK's Runner, and the session against a running Loom.

  • I can explain every line of this diff and how it interacts with the rest of Loom.

Checklist

  • make format-check, make lint, make typecheck and make test-unit pass (locally the named unit tests; the full suite in CI's pytest unit parts); the integration suite passes if server behaviour changed.
  • Generated files are regenerated in this PR, not by hand: the SDK op tables, docs/reference/configuration.md and the docs/reference/ tables (python scripts/codegen/docs_reference.py), the reach manifest, schemas/schema.sql (make schema-dump) and the Codex plugin copies (python3 scripts/codegen/agent_plugin_sync.py).
  • A new migration is additive and numbered after the latest on main; no merged migration is edited.
  • A behaviour change to any file a plugin ships (hooks/, lib/, bin/, skills/, .mcp.json, the Codex plugin-defaults.json) bumps both plugin manifests' version, and no other open PR uses that version.
  • The frontend builds (npm --prefix frontend run build) and its tests pass, if frontend/ changed.
  • Docs under docs/ describe the system as it now is, and this description names any operator steps and wire changes.
  • Repository text has no dates, people, host names, internal namespaces, ticket or decision numbers; the history goes in this description (tests/unit/test_public_copy.py).
  • Commits are signed off (git commit -s), as CONTRIBUTING.md asks.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: zlareb1 <lareb.zafar@clickhouse.com>
if (user !== undefined && ["", "-"].includes(user.trim())) {
throw new Error(`userId names a loom user or is undefined; ${JSON.stringify(user)} names none`);
}
const prefix = (opts.keyPrefix ?? "openai-agents").replace(/^\/+|\/+$/g, "");

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants