Как настроить агента с памятью (conversation history)

Результат: после выполнения инструкции у вас будет агент с памятью conversation history, который помнит предыдущий ход без ручной склейки сообщений. В воспроизводимом варианте ниже вы настроите это через OpenAI Agents SDK в Python и проверите память на двух вопросах: первый ответ должен содержать San Francisco, второй — California.

• ⏱️ Время: 15–25 минут
• 🎯 Сложность: средний
• 💰 Стоимость: зависит от выбранной модели и endpoint; точную ставку перед запуском проверьте на официальной странице Pricing
• 🛠️ Что потребуется: Python 3.10+, доступ к OpenAI API, пакет openai-agents 0.21.1, один выбранный способ хранения истории на один разговор
• 📌 Актуальная версия: по состоянию на 2026-08-19 в PyPI опубликован openai-agents 0.21.1; по JS есть расхождение между GitHub Releases (v0.11.5) и main-веткой (0.14.1), поэтому версию для pinning проверьте отдельно

Практический вердикт: если вам нужен самый короткий и проверяемый путь к памяти агента, используйте один и тот же SQLiteSession в Python Agents SDK для каждого хода диалога. Если нужна OpenAI-hosted история или continuation на стороне OpenAI, переходите на OpenAIConversationsSession либо previous_response_id/conversationId, но сначала проверьте retention, Zero Data Retention и региональные ограничения.

Какой способ памяти выбрать

Для conversation history у OpenAI сейчас есть два практических подхода: клиентски управляемая session в Agents SDK и серверно управляемое состояние разговора через OpenAI. Ключевое правило одно: для одного разговора выберите одну стратегию хранения истории и не смешивайте её в том же run с другой.

Если вам нужно шире понять терминологию, полезно отдельно свериться с материалом Память агента (Agent Memory). Если кроме истории диалога вам понадобятся внешние знания, это уже соседняя задача, и для неё подходит отдельная инструкция Как настроить RAG с LlamaIndex.

Для длинных разговоров в документации также упомянут OpenAIResponsesCompactionSession и для Python, и для JS. Если вам нужно просто «помнить предыдущие реплики», начинать всё равно проще с обычной session.

Пошагово: как настроить агента с памятью в Python

1. Зафиксируйте одну стратегию памяти на один разговор.

   Для этой инструкции используйте session из Python Agents SDK. Не комбинируйте её в том же run с conversation_id, previous_response_id или auto_previous_response_id. Это принципиально: одна беседа — одна стратегия сохранения истории.

   Ожидаемый результат: вы заранее решили, что память будет жить в одной session, а не в смеси session и server-managed continuation.

2. Установите Python SDK.

   На PyPI текущий пакет — openai-agents 0.21.1, требование — Python 3.10 или новее.

   pip install openai-agents==0.21.1

   Ожидаемый результат: пакет установлен в среду с Python 3.10+.

3. Подготовьте API-доступ.

   Для вызовов OpenAI нужен действующий API key. В документации по OpenAIConversationsSession отдельно указано, что для вызовов Conversations API требуется OPENAI_API_KEY или явный apiKey. Точный способ хранения секрета зависит от вашей среды; в этой инструкции важно, чтобы код мог делать запросы без ручной передачи всей истории между ходами.

   Ожидаемый результат: ваш проект может обращаться к OpenAI API, а вы не планируете вставлять предыдущие реплики вручную в каждый следующий запрос.

4. Создайте один session-объект и передавайте его в каждый Runner.run().

   Минимальный пример следует официальному паттерну из раздела Sessions для Python: один агент, одна session и два последовательных хода.

   import asyncio
   from agents import Agent, Runner, SQLiteSession
   
   async def main():
       agent = Agent(
           name="Memory demo",
           instructions="You are a helpful assistant.",
       )
   
       session = SQLiteSession("conversation_demo")
   
       result = await Runner.run(
           agent,
           "What city is the Golden Gate Bridge in?",
           session=session,
       )
       print(result.final_output)
   
       result = await Runner.run(
           agent,
           "What state is it in?",
           session=session,
       )
       print(result.final_output)
   
   asyncio.run(main())

   Ожидаемый результат: в коде один и тот же объект session передаётся в оба вызова Runner.run().

5. Запустите скрипт и проверьте перенос контекста между ходами.

   По документации session автоматически поддерживает conversation history: перед каждым run Runner достаёт предыдущие элементы из session, а после run сохраняет новые. Вам не нужно вручную склеивать прошлые сообщения между первым и вторым вопросом.

   Ожидаемый результат: первый ответ должен содержать San Francisco, второй — California. Формулировка ответа может отличаться, но эти значения должны присутствовать.

6. Добавьте базовое управление памятью разговора.

   Python sessions поддерживают методы get_items(), add_items(), pop_item() и clear_session(). Если история растёт слишком сильно, ограничьте объём подгружаемых элементов через SessionSettings(limit=N).

   Ожидаемый результат: вы можете просмотреть, дополнить, удалить или очистить историю без ручной сборки prompt, а также ограничить объём истории перед каждым run.

Как проверить, что всё работает

1. Запустите пример без изменений. Он должен сделать два последовательных run с одним и тем же session.
2. Проверьте первый ответ. Он должен содержать San Francisco.
3. Проверьте второй ответ. Он должен содержать California, хотя во втором вопросе город и мост уже не повторяются.
4. Убедитесь, что память идёт из session. Если второй вопрос сработал без ручной передачи полного диалога, значит history действительно была извлечена автоматически перед вторым run.
5. При необходимости проверьте содержимое session через get_items(). Это дополнительная проверка, что после двух ходов в памяти разговора уже есть сохранённые элементы.

Частые ошибки и исправления

• ❌ Ошибка: вы создаёте новую session на каждый ход.
  ✅ Решение: используйте один и тот же объект session для всех вызовов Runner.run() внутри одного разговора. Если session меняется, агент будет видеть беседу как новую.
• ❌ Ошибка: вы одновременно используете session и conversation_id или previous_response_id.
  ✅ Решение: выберите одну стратегию persistence на разговор. Для Python docs прямо запрещают комбинировать session в том же run с conversation_id, previous_response_id и auto_previous_response_id.
• ❌ Ошибка: вы ожидаете Zero Data Retention при использовании /v1/conversations.
  ✅ Решение: учитывайте, что /v1/conversations хранит application state до удаления и не является Zero Data Retention eligible. Если для вас критичен режим ZDR, отдельно проверьте путь через /v1/responses, где под ZDR store принудительно становится false.
• ❌ Ошибка: длинный разговор разрастается и начинает тянуть слишком много истории.
  ✅ Решение: ограничьте объём истории через SessionSettings(limit=N) или рассмотрите OpenAIResponsesCompactionSession, который в документации указан как вариант для длинных разговоров.
• ❌ Ошибка: вы пытаетесь жёстко закрепить JS-версию, не сверив источники.
  ✅ Решение: перед установкой или pinning проверьте опубликованную версию отдельно: в исходных материалах есть расхождение между GitHub Releases (v0.11.5) и packages/agents/package.json в main (0.14.1).

Безопасность и ограничения

Здесь важнее не сама session, а то, где фактически живёт состояние разговора и как на него распространяются правила retention.

• /v1/conversations: application state хранится до удаления и не подходит для Zero Data Retention.
• /v1/responses: application state удерживается 30 дней по умолчанию или при store=true; под Zero Data Retention параметр store принудительно становится false.
• Стоимость: она зависит от модели и endpoint. В pricing docs отдельно указано, что для regional processing endpoints есть наценка 10% на eligible models, выпущенные 2026-03-05 или позже. Поэтому точную ставку перед продакшеном всегда проверяйте на live-странице Pricing.
• Регион обработки: OpenAI пишет, что eligible API customers могут выбрать U.S. или Europe для data processing на поддерживаемых endpoint. На это нельзя полагаться без проверки вашей организации, проекта и конкретного endpoint.
• Редакционное ограничение: эта инструкция воспроизводимо покрывает Python-путь через session. Для JS логика памяти в источниках подтверждена, но опубликованные version signals расходятся, поэтому перед установкой и pinning проверьте текущий пакет отдельно.

Что делать дальше

• Если вам нужна база знаний поверх memory, переходите к инструкции Как настроить RAG с LlamaIndex.
• Если хотите видеть, где agent теряет контекст и как проходят run, настройте observability для AI-агентов с LangSmith.
• Если следующий шаг — встроить агента в workflow, посмотрите как настроить AI-автоматизацию в n8n.
• Если вы ещё собираете базовую архитектуру, начните с простого AI-агента с LangChain, а затем переносите логику памяти в production-стек.

Источники

• Overview – OpenAI Agents SDK
• Running Agents | OpenAI Agents SDK
• Sessions | OpenAI Agents SDK
• Running Agents | OpenAI Agents SDK
• Data controls in the OpenAI platform
• Pricing | OpenAI API
• Business data privacy, security, and compliance | OpenAI
• openai-agents · PyPI
• Releases · openai/openai-agents-js
• packages/agents/package.json at main · openai/openai-agents-js
• Releases · openai/openai-agents-python

Вопросы и ответы

Можно ли обойтись без session?

Да. В JS docs указано, что session обычно не нужен, если вы уже используете OpenAI-managed conversationId или previousResponseId. Для continuation через Responses API передают result.lastResponseId как previousResponseId и отправляют только следующий user turn.

Почему агент «забывает» прошлую реплику?

Чаще всего причина одна из двух: вы создаёте новую session на каждый ход или смешиваете session с другой persistence-стратегией в том же run. Для одного разговора нужен один и тот же способ хранения истории.

Что выбрать для длинных разговоров?

Сначала попробуйте ограничить объём подтягиваемой истории через SessionSettings(limit=N). Если у вас именно длинные диалоги, в Python и JS docs отдельно указан OpenAIResponsesCompactionSession.

Можно ли использовать Zero Data Retention с Conversations API?

Нет, для /v1/conversations это не подходит: endpoint хранит application state до удаления и не является Zero Data Retention eligible.

Можно ли выбрать регион обработки данных?

OpenAI пишет, что eligible API customers могут выбирать U.S. или Europe для data processing на поддерживаемых endpoint. Это нужно подтверждать отдельно для вашей организации, проекта и конкретного endpoint.