Сессии агентов

Important

Эта функция доступна в бета-версии.

Сессии агента предоставляют вашим агентам долговременное, независимое от фреймворка хранилище состояния сессии: состояние, которое агент или фреймворк сохраняет для одного взаимодействия. Чаще всего это история диалога — упорядоченная запись сообщений, вызовов инструментов и результатов, которую агент читает в начале цикла и пополняет по мере работы. Это также может быть любое другое состояние, в котором фреймворк сохраняет взаимодействие, например, граф LangGraph. Azure Databricks хранит его в Lakebase и управляет хранилищем за вас, так что вы не создаёте и не управляете базой данных.

Note

Во время предварительного просмотра вам выставляется счет за базовый экземпляр Lakebase, который хранит ваши сессии. За сами сессии агента дополнительные сборы не взимаются. Цены могут меняться по мере прохождения предварительного просмотра.

Используйте сессии агентов, когда хотите:

  • Сохраняйте историю переписок агента, чтобы она выдержала перезагрузку и могла быть возобновлена позже.
  • Восстановить полный контекст (включая вызовы инструментов и рассуждение) в следующем сообщении.
  • Просматривайте список прошлых бесед, возобновляйте их и создавайте ответвления в собственном интерфейсе.

Сессии агента содержат состояние одного взаимодействия (краткосрочное, состояние в сессии). Для долгосрочной памяти, сохраняющейся между разговорами, используйте память агента.

Требования

  • Установите Python 3.10 или выше, чтобы использовать AgentKit SDK. AgentKit SDK — это Databricks Python-клиент для API агентов, которые используются в приведённых ниже примерах. Вы также можете вызвать REST API напрямую с любого языка, без необходимости использовать Python.

Как работают сессии агентов

Иерархия ресурсов сессий агента: хранилище сессий содержит множество сессий, и каждая сессия содержит множество упорядоченных элементов сессии.

Сессии агентов имеют три уровня:

  • Хранилище сессий — это контейнер с ограничением рабочего пространства для сессий агента. Создание магазина автоматически обеспечивает резервное хранилище Lakebase. Выберите идентификатор магазина, уникальный в пределах рабочего пространства.
  • Сессия — это одно длительное взаимодействие (обычно разговорная тема) внутри магазина. Сессия определяется следующим образом:
    • actor_id (требуется): кому принадлежит сессия, например, конечному пользователю или другому агенту. Он группирует все сессии по одному предмету, чтобы можно было перечислить и отфильтровать их вместе. Когда вы создаёте приложение для каждого пользователя, установите actor_id ID пользователя (например, подтверждённую идентификацию конечного пользователя из аутентификации вашего приложения), чтобы сессии каждого пользователя оставались сгруппированными. Задавайте это из доверенного контекста приложения, а не как значение, предоставленное моделью или пользователем.
    • session_id (по желанию): идентификатор, выбранный вызывающим для взаимодействия. Сервис создаёт его, если вы его не указываете.
    • parent_session_id (необязательно): делает сессию дочерней сессией другой сессии в хранилище, например, беседой субагента. Устанавливайте это при создании сессии.
  • Элемент сессии — это одна запись в упорядоченной истории сессии. Каждый элемент содержит непрозрачное, совместимое data с JSON значение, такое как сообщение, вызов инструмента, результат инструмента или логический блок. Azure Databricks назначает каждому элементу item_id и create_time и не проверяет и не подтверждает его содержимое. Объекты неизменны после их добавления.

Сервис поддерживает детерминированный порядок для элементов сессии и авторизирует каждую операцию против хранилища сессии.

Get started

Эти примеры настраивают сессии агента для агента поддержки: он создаёт хранилище сессий, начинает сессию для одного разговора, добавляет реплики диалога и читает историю по последующему запросу. Выбирайте клиента, который подходит вашему проекту.

AgentKit SDK

AgentKit SDK — это Databricks Python-клиент для API агентов, распространяемый в пакетеdatabricks-agentbricks. Он аутентифицируется с помощью SDK WorkspaceClientDatabricks .

  1. Установите SDK AgentKit:

    pip install databricks-agentbricks

  2. Создайте хранилище сеансов, затем запустите сеанс для одной беседы. actor_id — кому принадлежит разговор; опциональное session_id уникально определяет этот разговор:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
session_store = client.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Добавляйте повороты разговора, пока агент бежит. Каждый элемент соответствует любому совместимому с JSON значением:

    session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

  4. При следующем запросе перезагрузите сессию и прочитайте её полную историю, чтобы восстановить контекст:

    session = session_store.get("case-456")
# Request chronological order; list_items defaults to newest-first and auto-pages.
history = [item.data for item in session.list_items(order_by="create_time asc")]

API REST

Клиенты вызывают REST API под /api/2.0/agents/session-stores. Вызывайте его напрямую для языков, отличных от Python.

  1. Генерируйте токен OAuth с помощью CLI Databricks:

    databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

  2. Создайте магазин сессий для вашего агента:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_id=support-agent-sessions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"description": "Support agent conversation history"}'

  3. Начать сессию для одного разговора. actor_id указывает, кому он принадлежит; session_id уникально определяет эту беседу:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions?session_id=case-456" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "customer-123"}'

  4. Добавьте реплику в разговор во время работы агента:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items:append" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"items": [{"data": {"type": "message", "role": "user", "content": "I need help with my cluster."}}]}'

  5. Прочитайте историю в хронологическом порядке, чтобы восстановить контекст:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"

Клиенты также поддерживают удаление самого последнего элемента, очистку элементов сеанса и создание независимой копии разговора (при необходимости — до указанного элемента). У форка нет родительской сессии, и удаление исходной сессии не удаляет её. Удаление сессии всегда приводит к удалению дочерних сессий и их элементов.

Обеспечьте хранение сеанса платформы агента с помощью сеансов агента

Фреймворки агентов, такие как OpenAI Agents SDK и Claude Agent SDK, читают историю разговоров в начале запуска и добавляют новые элементы в конце. Хранилище сеансов непосредственно соответствует этому шаблону:

Работа фреймворка Вызов хранилища сеансов
Читать историю list_items в хронологическом порядке (order_by="create_time asc")
Добавить элементы хода append Новые предметы
Отменить последний элемент pop Самый свежий пункт
Очистите тему clear Пункты сессии

Область и доступ

Сессии агента хранят элементы сессии в виде непрозрачных, совместимых с JSON значений: сервис сохраняет и возвращает всё, что добавляет ваш агент или фреймворк, не интерпретируя это. Он не добавляет ресурсы управления выполнением, такие как запуски, контрольные точки или согласования, в качестве самостоятельных сущностей, хотя фреймворк, сериализующий это состояние, может сохранять его в виде элементов.

Хранилища сеансов ограничены рабочим пространством, а доступ предоставляется на уровне хранилища. Контроль доступа к хранилищу охватывает сеансы хранилища. Любой пользователь рабочего пространства может перечислять хранилища сессий и получать их, включая их идентификаторы и описания. Поля actor_id и metadata поддерживают только группировку и фильтрацию; они не предоставляют и не ограничивают доступ. Установите actor_id из контекста доверенного приложения, а не из значения, предоставленного моделью или пользователем.

Чтобы другой принципал, например сервисный директор вашего агента, использовал хранилище, предоставьте ему доступ с помощью операции предоставления разрешения (session_store.grant_permission(principal_id) в SDK AgentKit). Доступ может предоставить только создатель магазина или администратор рабочего пространства.

Сессии агента и память агента независимы. Удаление сеанса или хранилища сеансов не удаляет память, хранящуюся в хранилище памяти. Чтобы построить долгосрочную память из сессий в хранилище, создайте поток памяти.

Дальнейшие действия

  • Последнее обновление: