OpenAI Agents SDK

A durable, Rekall-backed Session for the OpenAI Agents SDK. The @rekall/openai-agents package gives your agents conversation memory that survives restarts and moves across hosts — in one object.

Overview

The OpenAI Agents SDK automatically fetches prior items and persists new ones through its Session interface. RekallSession implements that interface against Rekall's execution-memory layer, so switching from the SDK's in-memory session to a durable one requires no other code changes. There are zero backend changes — it's a pure client of existing endpoints.

history

Survives restarts

Conversation history is stored server-side, not in process memory.

dns

Cross-host

Any worker with the session id can resume the conversation.

swap_horiz

Drop-in

Implements the SDK Session interface — no other code changes.

Installation

Terminal
npm install @rekall/openai-agents

Usage

Construct a RekallSession with a sessionId (the persistence key) and pass it in the run options:

agent.ts
import { Agent, run } from '@openai/agents';
import { RekallSession } from '@rekall/openai-agents';


const agent = new Agent({
  name: 'Tour guide',
  instructions: 'Answer with compact travel facts.',
});


const session = new RekallSession({
  apiUrl: 'https://api.rekall.app',   // or http://localhost:9876 in dev
  apiKey: process.env.REKALL_API_KEY, // rk_… key, or accessToken: 'rat_…'
  sessionId: 'user-42',                // the persistence key
});


await run(agent, 'What city is the Golden Gate Bridge in?', { session });
await run(agent, 'What state is it in?', { session });   // remembers the prior turn

Resume anywhere

Because history lives in Rekall keyed by sessionId, the process can restart or a different host can pick up the same session id and continue the conversation exactly where it left off.

Session Contract

RekallSession implements the SDK's full Session interface:

  • check_circlegetSessionId — returns the persistence key
  • check_circlegetItems(limit?) — reads the stored AgentInputItem[] history
  • check_circleaddItems — appends new items to the session
  • check_circlepopItem — removes and returns the most recent item
  • check_circleclearSession — clears the stored history for the session

How It Persists

The session's full AgentInputItem[] history is stored in one Rekall execution-memory external-state blob with provider: "openai-agents" and providerAgentId: sessionId. This is the same execution-memory layer that powers Rekall's human-in-the-loop pause and resume.

Authentication

Pass apiKey (rk_…) or accessToken (rat_…), sent as a Bearer token; or pass headers: { 'x-user-id': '…' } for local dev against a header-auth server.

Next Steps

Browse all framework adaptersUnderstand execution memory and external stateExplore human-in-the-loop patterns
Rekall
rekall