세션

세션은 Agents SDK에 지속형 메모리 계층을 제공합니다. Session 인터페이스를 구현한 어떤 객체든 Runner.run에 제공하면, 나머지는 SDK가 처리합니다. 세션이 있으면 러너는 자동으로 다음을 수행합니다.

1. 이전에 저장된 대화 항목을 가져와 다음 턴 앞에 붙입니다.
2. 각 실행이 완료된 후 새 사용자 입력과 어시스턴트 출력을 지속화합니다.
3. 새로운 사용자 텍스트로 러너를 호출하든 인터럽션(중단 처리)된 RunState에서 재개하든, 향후 턴을 위해 세션을 계속 사용할 수 있게 유지합니다.

이로써 수동으로 toInputList()를 호출하거나 턴 사이의 히스토리를 연결할 필요가 없어집니다. TypeScript SDK에는 두 가지 구현이 포함되어 있습니다: Conversations API용 OpenAIConversationsSession과 로컬 개발을 위한 MemorySession. 이들은 Session 인터페이스를 공유하므로, 자체 스토리지 백엔드를 연결할 수 있습니다. Conversations API를 넘어서는 영감을 얻으려면 examples/memory/(Prisma, 파일 기반 등) 아래의 샘플 세션 백엔드를 살펴보세요.

팁: 이 페이지의 OpenAIConversationsSession 예제를 실행하려면 SDK가 Conversations API를 호출할 수 있도록 환경 변수 OPENAI_API_KEY를 설정하거나(또는 세션 생성 시 apiKey를 제공) 하세요.

---

빠른 시작

OpenAIConversationsSession을 사용하여 Conversations API와 메모리를 동기화하거나, 다른 어떤 Session 구현으로 교체하세요.

Conversations API를 세션 메모리로 사용

import { Agent, OpenAIConversationsSession, run } from '@openai/agents';

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

// Any object that implements the Session interface works here. This example uses
// the built-in OpenAIConversationsSession, but you can swap in a custom Session.
const session = new OpenAIConversationsSession();

const firstTurn = await run(agent, 'What city is the Golden Gate Bridge in?', {
  session,
});
console.log(firstTurn.finalOutput); // "San Francisco"

const secondTurn = await run(agent, 'What state is it in?', { session });
console.log(secondTurn.finalOutput); // "California"

동일한 세션 인스턴스를 재사용하면, 매 턴마다 에이전트가 전체 대화 히스토리를 수신하고 새 항목이 자동으로 지속화됩니다. 다른 Session 구현으로 전환하더라도 추가 코드 변경은 필요 없습니다.

---

러너가 세션을 사용하는 방식

• 각 실행 전 세션 히스토리를 가져와 새 턴 입력과 병합하고, 합쳐진 목록을 에이전트에 전달합니다.
• 비스트리밍 실행 후 한 번의 session.addItems() 호출로 최신 턴의 원본 사용자 입력과 모델 출력을 모두 지속화합니다.
• 스트리밍 실행의 경우 사용자 입력을 먼저 기록하고, 턴이 완료되면 스트리밍된 출력을 이어서 추가합니다.
• RunResult.state에서 재개할 때(승인 또는 기타 인터럽션) 동일한 session을 계속 전달하세요. 재개된 턴은 입력을 다시 준비하지 않고 메모리에 추가됩니다.

---

히스토리 검사 및 편집

세션은 간단한 CRUD 헬퍼를 제공하므로 “실행 취소”, “채팅 지우기”, 감사 기능을 구축할 수 있습니다.

저장된 항목 읽기 및 편집

import { OpenAIConversationsSession } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents-core';

// Replace OpenAIConversationsSession with any other Session implementation that
// supports get/add/pop/clear if you store history elsewhere.
const session = new OpenAIConversationsSession({
  conversationId: 'conv_123', // Resume an existing conversation if you have one.
});

const history = await session.getItems();
console.log(`Loaded ${history.length} prior items.`);

const followUp: AgentInputItem[] = [
  {
    type: 'message',
    role: 'user',
    content: [{ type: 'input_text', text: 'Let’s continue later.' }],
  },
];
await session.addItems(followUp);

const undone = await session.popItem();

if (undone?.type === 'message') {
  console.log(undone.role); // "user"
}

await session.clearSession();

session.getItems()는 저장된 AgentInputItem[]을 반환합니다. popItem()을 호출하면 마지막 항목을 제거합니다. 에이전트를 다시 실행하기 전에 사용자 수정에 유용합니다.

---

자체 스토리지 사용

Session 인터페이스를 구현하여 Redis, DynamoDB, SQLite 또는 다른 데이터 스토어로 메모리를 지원하세요. 필요한 것은 다섯 개의 비동기 메서드뿐입니다.

커스텀 인메모리 세션 구현

import { Agent, run } from '@openai/agents';
import { randomUUID } from '@openai/agents-core/_shims';
import { logger, Logger } from '@openai/agents-core/dist/logger';
import type { AgentInputItem, Session } from '@openai/agents-core';

/**
 * Minimal example of a Session implementation; swap this class for any storage-backed version.
 */
export class CustomMemorySession implements Session {
  private readonly sessionId: string;
  private readonly logger: Logger;

  private items: AgentInputItem[];

  constructor(
    options: {
      sessionId?: string;
      initialItems?: AgentInputItem[];
      logger?: Logger;
    } = {},
  ) {
    this.sessionId = options.sessionId ?? randomUUID();
    this.items = options.initialItems
      ? options.initialItems.map(cloneAgentItem)
      : [];
    this.logger = options.logger ?? logger;
  }

  async getSessionId(): Promise<string> {
    return this.sessionId;
  }

  async getItems(limit?: number): Promise<AgentInputItem[]> {
    if (limit === undefined) {
      const cloned = this.items.map(cloneAgentItem);
      this.logger.debug(
        `Getting items from memory session (${this.sessionId}): ${JSON.stringify(cloned)}`,
      );
      return cloned;
    }
    if (limit <= 0) {
      return [];
    }
    const start = Math.max(this.items.length - limit, 0);
    const items = this.items.slice(start).map(cloneAgentItem);
    this.logger.debug(
      `Getting items from memory session (${this.sessionId}): ${JSON.stringify(items)}`,
    );
    return items;
  }

  async addItems(items: AgentInputItem[]): Promise<void> {
    if (items.length === 0) {
      return;
    }
    const cloned = items.map(cloneAgentItem);
    this.logger.debug(
      `Adding items to memory session (${this.sessionId}): ${JSON.stringify(cloned)}`,
    );
    this.items = [...this.items, ...cloned];
  }

  async popItem(): Promise<AgentInputItem | undefined> {
    if (this.items.length === 0) {
      return undefined;
    }
    const item = this.items[this.items.length - 1];
    const cloned = cloneAgentItem(item);
    this.logger.debug(
      `Popping item from memory session (${this.sessionId}): ${JSON.stringify(cloned)}`,
    );
    this.items = this.items.slice(0, -1);
    return cloned;
  }

  async clearSession(): Promise<void> {
    this.logger.debug(`Clearing memory session (${this.sessionId})`);
    this.items = [];
  }
}

function cloneAgentItem<T extends AgentInputItem>(item: T): T {
  return structuredClone(item);
}

const agent = new Agent({
  name: 'MemoryDemo',
  instructions: 'Remember the running total.',
});

// Using the above custom memory session implementation here
const session = new CustomMemorySession({
  sessionId: 'session-123-4567',
});

const first = await run(agent, 'Add 3 to the total.', { session });
console.log(first.finalOutput);

const second = await run(agent, 'Add 4 more.', { session });
console.log(second.finalOutput);

커스텀 세션을 통해 보존 정책을 강제하고, 암호화를 추가하거나, 지속화 전에 각 대화 턴에 메타데이터를 첨부할 수 있습니다.

---

히스토리와 새 항목 병합 제어

실행 입력으로 AgentInputItem 배열을 전달할 때, 저장된 히스토리와 결정적으로 병합하기 위해 sessionInputCallback을 제공하세요. 러너는 기존 히스토리를 로드하고, 모델 호출 전에 콜백을 호출하며, 반환된 배열을 해당 턴의 완전한 입력으로 모델에 전달합니다. 이 후크는 오래된 항목을 잘라내거나, 도구 결과의 중복을 제거하거나, 모델이 보길 원하는 컨텍스트만 강조하는 데 적합합니다.

sessionInputCallback으로 히스토리 잘라내기

import { Agent, OpenAIConversationsSession, run } from '@openai/agents';
import type { AgentInputItem } from '@openai/agents-core';

const agent = new Agent({
  name: 'Planner',
  instructions: 'Track outstanding tasks before responding.',
});

// Any Session implementation can be passed here; customize storage as needed.
const session = new OpenAIConversationsSession();

const todoUpdate: AgentInputItem[] = [
  {
    type: 'message',
    role: 'user',
    content: [
      { type: 'input_text', text: 'Add booking a hotel to my todo list.' },
    ],
  },
];

await run(agent, todoUpdate, {
  session,
  // function that combines session history with new input items before the model call
  sessionInputCallback: (history, newItems) => {
    const recentHistory = history.slice(-8);
    return [...recentHistory, ...newItems];
  },
});

문자열 입력의 경우 러너가 히스토리를 자동으로 병합하므로, 콜백은 선택 사항입니다.

---

승인 및 재개 가능한 실행 처리

Human-in-the-loop 흐름은 종종 승인을 기다리기 위해 실행을 일시 중지합니다:

const result = await runner.run(agent, 'Search the itinerary', {
  session,
  stream: true,
});

if (result.requiresApproval) {
  // ... collect user feedback, then resume the agent in a later turn
  const continuation = await runner.run(agent, result.state, { session });
  console.log(continuation.finalOutput);
}

이전에 생성된 RunState에서 재개하면, 단일 대화 히스토리를 보존하기 위해 새 턴이 동일한 메모리 레코드에 추가됩니다. Human-in-the-loop (HITL) 흐름은 완전히 호환되며, 승인 체크포인트는 여전히 RunState를 통해 왕복하는 동안 세션이 전체 대화 기록을 유지합니다.