openai-agents-python/docs/ko/sessions/sqlalchemy_session.md
2026-11-10 07:54:51 +00:00

3.5 KiB

search
exclude
true

SQLAlchemy 세션

SQLAlchemySession은 SQLAlchemy를 사용하여 운영 환경에 적합한 세션 구현을 제공하므로, SQLAlchemy에서 지원하는 모든 데이터베이스(PostgreSQL, MySQL, SQLite 등)를 세션 스토리지로 사용할 수 있습니다.

설치

SQLAlchemy 세션을 사용하려면 sqlalchemy optional-dependency extra와 데이터베이스 URL에 맞는 비동기 데이터베이스 드라이버가 필요합니다.

아래 SQLite 예제(sqlite+aiosqlite://)를 사용하려면 extra와 함께 aiosqlite을 설치합니다.

pip install 'openai-agents[sqlalchemy]' aiosqlite

이 extra에는 postgresql+asyncpg://로 시작하는 PostgreSQL URL용 asyncpg가 이미 포함되어 있습니다. mysql+aiomysql://으로 시작하는 MySQL URL을 사용하려면 extra와 함께 aiomysql을 설치합니다. 드라이버의 rsa extra는 MySQL의 SHA-256 인증 방식에 필요한 종속성을 제공합니다.

pip install 'openai-agents[sqlalchemy]' 'aiomysql[rsa]'

빠른 시작

데이터베이스 URL 사용

가장 간단하게 시작하는 방법은 다음과 같습니다.

import asyncio
from agents import Agent, Runner
from agents.extensions.memory import SQLAlchemySession


async def main():
    agent = Agent("Assistant")

    # Create session using database URL
    session = SQLAlchemySession.from_url(
        "user-123", url="sqlite+aiosqlite:///:memory:", create_tables=True
    )

    result = await Runner.run(agent, "Hello", session=session)
    print(result.final_output)


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

기존 엔진 사용

기존 SQLAlchemy 엔진이 있는 애플리케이션에서는 다음과 같이 사용합니다.

import asyncio
from agents import Agent, Runner
from agents.extensions.memory import SQLAlchemySession
from sqlalchemy.ext.asyncio import create_async_engine


async def main():
    # Create your database engine
    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")

    agent = Agent("Assistant")
    session = SQLAlchemySession("user-456", engine=engine, create_tables=True)

    result = await Runner.run(agent, "Hello", session=session)
    print(result.final_output)

    # Clean up
    await engine.dispose()


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

비 ASCII 텍스트 저장

기본적으로 SQLAlchemySession은 세션 항목을 JSON으로 직렬화할 때 비 ASCII 문자를 이스케이프합니다. 이를 통해 기존 저장 형식을 유지하면서도 항목을 불러올 때 원래 텍스트로 정상적으로 복원할 수 있습니다.

저장된 JSON에서 다국어 텍스트를 읽을 수 있는 상태로 유지하려면 ensure_ascii=False을 설정합니다.

session = SQLAlchemySession.from_url(
    "user-123",
    url="sqlite+aiosqlite:///conversations.db",
    create_tables=True,
    ensure_ascii=False,
)

기존 엔진을 사용할 때는 동일한 옵션을 SQLAlchemySession(...)에 직접 전달할 수 있습니다. 이 설정은 데이터베이스에 저장되는 JSON 표현만 변경하며, 세션 메서드가 반환하는 값은 변경하지 않습니다.

API 레퍼런스

  • [SQLAlchemySession][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - 주요 클래스
  • [Session][agents.memory.session.Session] - 기본 세션 프로토콜