Encrypted sessions

Encrypted sessions (암호화 세션)

EncryptedSession은 모든 세션 구현에 투명한 암호화를 제공해서, 오래된 항목의 자동 만료와 함께 대화 데이터를 보호해요.

출처: 문서

본문

기능

• 투명한 암호화: 모든 세션을 Fernet 암호화로 감싸요.
• 세션별 키: 세션마다 고유 암호화를 위한 HKDF 키 파생을 사용해요.
• 자동 만료: TTL이 지나면 오래된 항목을 조용히 건너뛰어요.
• 드롭인 교체: 기존 세션 구현 어디에나 동작해요.

설치

암호화 세션에는 encrypt extra가 필요해요.

pip install 'openai-agents[encrypt]'

빠른 시작

이 예제는 인메모리 SQLiteSession을 사용하고 실행마다 새 암호화 키를 생성해요. 내장 세션은 별도 데이터베이스 드라이버가 필요 없어요. 영속 저장을 위해서는 아래 암호화 키 안내에 따라 프로세스 재시작 간에 키를 보관·재사용하세요.

import asyncio
from cryptography.fernet import Fernet
from agents import Agent, Runner, SQLiteSession
from agents.extensions.memory import EncryptedSession

async def main():
    agent = Agent("Assistant")
    encryption_key = Fernet.generate_key().decode("ascii")

    underlying_session = SQLiteSession("user-123")
    try:
        session = EncryptedSession(
            session_id="user-123",
            underlying_session=underlying_session,
            encryption_key=encryption_key,
            ttl=600  # 10 minutes
        )

        result = await Runner.run(agent, "Hello", session=session)
        print(result.final_output)
    finally:
        underlying_session.close()

if __name__ == "__main__":
    asyncio.run(main())

구성

암호화 키

Fernet.generate_key()로 생성한 키나 애플리케이션의 시크릿 관리 시스템이 프로비저닝한 높은 엔트로피 무작위 시크릿 같은, 암호학적으로 무작위·높은 엔트로피 마스터 키를 사용하세요. 암호화 키로 비밀번호, 기억하기 쉬운 문구, 하드코딩된 샘플 값을 사용하지 마세요.

from cryptography.fernet import Fernet

# Generate once when provisioning a new key, then store the value securely.
encryption_key = Fernet.generate_key().decode("ascii")

영속 저장을 위해 키를 데이터 암호화에 쓰기 전에 한 번 생성하고 그 값을 시크릿 매니저나 다른 안전한 저장소에 저장하세요. 모든 프로세스 시작에서 같은 키를 로드하세요. 아래 스니펫은 배포가 저장된 키를 SESSION_ENCRYPTION_KEY로 주입한다고 가정해요. 환경 변수 이름은 SDK 설정이 아니라 애플리케이션 관례예요.

import os
from agents.extensions.memory import EncryptedSession

encryption_key = os.environ["SESSION_ENCRYPTION_KEY"]
session = EncryptedSession(
    session_id="user-123",
    underlying_session=underlying_session,
    encryption_key=encryption_key,
    ttl=600
)

키를 비밀로 하고, 암호화된 세션 데이터베이스와 분리하세요. 재시작 후 기존 데이터를 읽으려면 같은 마스터 키와 같은 session_id를 쓰세요. 시작 시 교체 키를 생성하면 애플리케이션이 기존 레코드를 해독하지 못해요. encryption_key를 바꿔도 저장된 레코드는 다시 암호화되지 않아요. 기존 레코드는 여전히 원래 키가 필요하고 그 TTL의 적용을 받아요.

EncryptedSession은 역호환성을 위해 원시 문자열도 계속 받아요. 그 수용이 비밀번호나 다른 낮은 엔트로피 시크릿을 쓰라는 권장은 아니에요. SDK는 암호 강화가 아니라 세션별 키 파생에 HKDF를 사용해요. 세션 ID 소금은 세션 키를 분리하지만 비밀 엔트로피를 추가하지 않아요. 아래 Key derivation을 참고하세요.

TTL (time to live)

암호화된 항목이 유효한 시간을 설정하세요. 이 스니펫은 위에서 로드한 encryption_key를 재사용해요.

# Items expire after 1 hour
session = EncryptedSession(
    session_id="user-123",
    underlying_session=underlying_session,
    encryption_key=encryption_key,
    ttl=3600  # 1 hour in seconds
)

# Items expire after 1 day
session = EncryptedSession(
    session_id="user-123",
    underlying_session=underlying_session,
    encryption_key=encryption_key,
    ttl=86400  # 24 hours in seconds
)

다른 세션 타입과 사용

SQLite 세션과 함께

import os
from agents import SQLiteSession
from agents.extensions.memory import EncryptedSession

# Load the same securely stored key each time this database is opened.
encryption_key = os.environ["SESSION_ENCRYPTION_KEY"]

# Create encrypted SQLite session
underlying = SQLiteSession("user-123", "conversations.db")

session = EncryptedSession(
    session_id="user-123",
    underlying_session=underlying,
    encryption_key=encryption_key
)

SQLAlchemy 세션과 함께

아래 PostgreSQL 예제에는 encrypt와 sqlalchemy extra를 설치하세요. sqlalchemy extra는 postgresql+asyncpg:// URL이 쓰는 asyncpg 드라이버를 포함해요.

pip install 'openai-agents[encrypt,sqlalchemy]'

import os
from agents.extensions.memory import EncryptedSession, SQLAlchemySession

# Load the same securely stored key each time this database is opened.
encryption_key = os.environ["SESSION_ENCRYPTION_KEY"]

# Create encrypted SQLAlchemy session
underlying = SQLAlchemySession.from_url(
    "user-123",
    url="postgresql+asyncpg://user:pass@localhost/db",
    create_tables=True
)

session = EncryptedSession(
    session_id="user-123",
    underlying_session=underlying,
    encryption_key=encryption_key
)

애플리케이션은 SQLAlchemySession.from_url()이 만든 엔진을 폐기(dispose)할 책임이 있어요. 그 엔진을 쓰는 모든 SQLAlchemySession 인스턴스가 더 이상 필요 없어지면, 실행이 실패해도 애플리케이션의 정리 경로에서 await underlying.engine.dispose()를 호출하세요.

고급 세션 기능: EncryptedSession을 AdvancedSQLiteSession 같은 고급 세션 구현과 쓸 때 다음을 기억하세요.

• find_turns_by_content() 같은 메서드는 메시지 콘텐츠가 암호화돼 있어 효과적으로 동작하지 않아요.
• 콘텐츠 기반 검색은 암호화된 데이터에서 동작하므로 그 효과가 제한돼요.

키 파생

EncryptedSession은 HKDF(HMAC-based Key Derivation Function)로 세션마다 고유 암호화 키를 파생해요.

• 마스터 키: 내가 제공한 암호화 키
• 세션 소금: 세션 ID
• Info 문자열: "agents.session-store.hkdf.v1"
• 출력: 32바이트 Fernet 키

높은 엔트로피 마스터 키로 다른 세션 ID는 다른 파생 키를 만들어요. 같은 마스터 키와 세션 ID를 재사용하면 같은 파생 키가 만들어져, 애플리케이션이 이전에 저장한 만료되지 않은 항목을 해독할 수 있어요.

HKDF는 약한 마스터 키를 비밀번호 추측에 저항하게 만들지 않아요. 세션 ID는 추가 비밀 키 재료가 아니라 비밀 아닌 소금이에요. 키 파생과 비밀번호 강화의 구분은 cryptography HKDF 문서를 참고하세요.

자동 만료

항목이 TTL을 넘으면 검색 중 자동으로 건너뛰어져요.

# Items older than TTL are silently ignored
items = await session.get_items()  # Only returns non-expired items

# Expired items don't affect session behavior
result = await Runner.run(agent, "Continue conversation", session=session)

API 레퍼런스

• EncryptedSession — 메인 클래스
• Session — 기본 세션 프로토콜

더 알아보기 (Learn more)

• OpenAI Agents SDK 문서에서 더 많은 가이드를 확인하세요.