OpenAI Agents API保存持久会话

OpenAI Agents API（更准确地说是 OpenAI Agents SDK）保存持久会话，核心不是把上一次的回答手工拼回输入，而是给 Runner.run 传入一个稳定的会话对象。SDK 会在运行前读取历史，在运行完成后保存本轮产生的新条目。想在本地落盘，使用 SQLiteSession；想让 OpenAI 服务端管理会话，则使用 OpenAIConversationsSession 或直接复用 conversation_id。

官方文档：https://openai.github.io/openai-agents-python/sessions/

下面用 Python 说明最小可用写法，并把本地会话、服务端会话和 previous_response_id 的边界分开。

先选对持久化方式

Agents SDK 的“会话”有三条常用路线。session 把历史交给应用侧的存储实现，适合 SQLite、Redis、SQLAlchemy 等后端；conversation_id 是 OpenAI Conversations API 的服务端会话资源，适合多个进程共享；previous_response_id 则是 Responses API 的轻量续接方式，适合沿着上一条响应继续对话。

这三种方式不要在同一次运行里叠加。比如已经传入 session，就不要再同时传 conversation_id 或 previous_response_id，否则历史可能重复，且不容易判断究竟哪一层是事实来源。

用 SQLiteSession 把会话保存到文件

本地开发或单机服务可以先用 SQLite。只要数据库文件不变、会话 ID 不变，进程重新启动后就能重新创建一个指向相同历史的 SQLiteSession。安装包名是 openai-agents，导入模块名仍然是 agents。

python -m venv .venv
source .venv/bin/activate
# 安装 OpenAI Agents SDK，后续示例从 agents 模块导入
pip install openai-agents
# 只在当前终端设置密钥，实际项目请使用安全的环境变量管理
export OPENAI_API_KEY="sk-..."

最小示例可以让第一次提问写入历史，第二次提问只发送一个指代词，SDK 会从同一个会话中取回上一轮内容。

import asyncio
from agents import Agent, Runner, SQLiteSession


async def main() -> None:
    # 固定 session_id，并把历史写入文件，进程退出后仍可恢复
    session = SQLiteSession("user-42", "agent-conversations.db")
    agent = Agent(
        name="项目助手",
        instructions="用简洁中文回答，并记住当前项目的上下文。",
    )

    # 第一次运行会把用户输入和模型产生的新条目保存到 session
    first = await Runner.run(agent, "我们的服务使用 Python 和 SQLite。", session=session)
    print(first.final_output)

    # 第二次运行复用同一个 session，问题中的“它”可以引用上一轮上下文
    second = await Runner.run(agent, "它适合先做本地原型吗？", session=session)
    print(second.final_output)


if __name__ == "__main__":
    # 使用 asyncio 进入异步 Runner，异常会自然向上抛出便于记录
    asyncio.run(main())

这里的关键是 session_id 和数据库路径，而不是把 first.to_input_list() 永久存到业务表里。Session 会在每轮运行前读取历史，运行结束后只保存本轮的新条目。

进程重启后如何继续同一段对话

不要每次启动服务都随机生成新的会话 ID。登录用户、租户和业务会话可以组合成稳定的 ID，再从同一个数据库文件重新创建 Session。长对话还可以限制每次取回的条目数量，避免历史越长，单次输入成本越高。

from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession


async def continue_chat(user_id: str, text: str) -> str:
    # 业务层保证同一个用户使用同一个稳定 ID，数据库文件由部署配置提供
    session = SQLiteSession(f"support:{user_id}", "agent-conversations.db")
    agent = Agent(name="客服助手", instructions="结合已有对话回答当前问题。")

    # 只取最近一段历史，避免无界上下文；存储中的完整历史仍保留
    config = RunConfig(session_settings=SessionSettings(limit=50))
    result = await Runner.run(agent, text, session=session, run_config=config)
    return result.final_output

limit 控制的是本次运行取回多少条历史，并不等于删除数据库中的旧记录。如果业务需要真正归档、删除或脱敏，应在 Session 存储层设计明确的生命周期策略。

多实例服务改用 OpenAIConversationsSession

如果服务会在多个工作进程之间切换，或者不希望自己维护会话表，可以使用 OpenAIConversationsSession。第一次创建会话后保存返回的会话 ID，下一次用这个 ID 恢复。这个方案把历史放在 OpenAI 的 Conversations API 侧，应用只需要可靠地保存 ID。

from agents import Agent, OpenAIConversationsSession, Runner


async def server_managed_chat(conversation_id: str | None, text: str):
    # 没有 ID 时创建新会话；有 ID 时恢复同一个服务端会话
    session = OpenAIConversationsSession(conversation_id=conversation_id)
    agent = Agent(name="在线助手", instructions="保持多轮对话的上下文一致。")

    # SDK 会把新一轮输入追加到服务端会话，并返回可继续保存的 ID
    result = await Runner.run(agent, text, session=session)
    return result.final_output, session.conversation_id

在跨服务共享、水平扩展或需要服务端统一管理历史时，这条路线更自然；但它仍然需要在你的账户、数据库或业务令牌中保存会话 ID，并对数据保留和访问权限负责。

session、conversation_id 和 previous_response_id 有什么区别

可以用下面的判断快速选型：

如果选了 session，就让 Session 负责历史；如果选了服务端会话，就在每轮传递对应标识。不要一边把完整历史塞进 to_input_list()，一边再传 Session，除非你明确知道自己在做历史合并。

持久会话的三个工程边界

1. 稳定但可撤销的 ID：会话 ID 不要直接暴露邮箱、手机号或内部密钥。用户退出、删除数据或租户注销时，应能撤销对应映射。
2. 控制历史增长：使用 SessionSettings(limit=...) 做读取上限，长对话再考虑压缩或摘要；不要把“历史永久保存”和“每轮全部回放”混为一谈。
3. 中断恢复要复用同一会话：如果运行因为审批暂停，恢复时继续使用相同 Session 或相同服务端会话标识，避免把批准前后的条目写入两段不同历史。

常见问题

SQLiteSession 只传一个 ID 可以持久化吗？

只传一个 ID 时可以使用默认的轻量存储方式，但要做跨进程、跨重启的明确持久化，建议显式指定稳定的数据库文件路径，并确保部署环境不会在重启时清空它。

会话历史会自动限制长度吗？

默认会读取可用历史。可以用 SessionSettings(limit=N) 限制本次读取条数；这不会自动替你完成业务级摘要、合规删除或敏感字段脱敏。

可以同时传 session 和 previous_response_id 吗？

同一次运行不要这样做。先选择应用侧 Session 或 OpenAI 管理的续接机制，再围绕这一种方式保存和恢复状态。

总结一下：单机原型优先用带文件路径的 SQLiteSession，共享会话优先考虑 OpenAIConversationsSession 或 conversation_id，只想沿着上一条 Responses 响应继续时才使用 previous_response_id。会话 ID 的生命周期、历史长度和敏感数据处理，才是持久化上线前真正需要补齐的部分。