Память агента

Important

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

Память агента даёт вашим агентам долгосрочную память, которая сохраняется между разговорами. Azure Databricks хранит память в Lakebase и управляет хранением, индексацией и поиском, чтобы ваши агенты могли запоминать пользовательские предпочтения, прошлые решения и накопленный контекст без необходимости управлять базой данных.

Note

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

Используйте память агента, когда хотите, чтобы ваши агенты могли:

  • Помните предпочтения пользователей, факты и решения в разных разговорах.
  • Персонализируйте ответы, исходя из того, что агент узнал на предыдущих сессиях.
  • Делитесь накопленными знаниями между агентами и проектами.
  • Повышение точности и эффективности с течением времени.

Память агентов работает с агентами, построенными на любом фреймворке. Для краткосрочной истории разговоров в одном взаимодействии используйте сессии агента.

Requirements

  • Установите Python 3.10 или выше, чтобы использовать AgentKit SDK. AgentKit SDK — это Databricks Python-клиент для API агентов, которые используются в приведённых ниже примерах. Вы также можете вызвать REST API напрямую с любого языка, без необходимости использовать Python.
  • Чтобы использовать memory_store.put() или memory_store.list(path=...), установите databricks-agentbricks версии 0.6.0 и выше.

Как работает память агента

Иерархия ресурсов памяти агента: хранилище памяти содержит множество записей памяти, каждая из которых идентифицируется actor_id, необязательным session_id и путём и содержит содержимое и описание.

Память агента имеет два уровня:

  • Хранилище памяти — это контейнер воспоминаний агента в рамках рабочего пространства. Создание магазина автоматически обеспечивает резервное хранилище Lakebase. Вы обращаетесь к магазину по ID магазина, который выбираете при создании магазина.
  • Запись памяти — это отдельный элемент контента в магазине. Каждая запись содержит текст произвольного формата content, короткий description, используемый для поиска, и набор полей, которые упорядочивают и разделяют её:
    • actor_id (требуется): кому принадлежит память, например, конечному пользователю или другому агенту.
    • session_id (по желанию): сессия, к которой принадлежит memory. Оставьте его неустановленным, если эта память действует во всех сеансах актёра.
    • path (требуется): путь, похожий на файловую систему, который организует записи внутри актора, например /preferences/response-style.md.

Запись однозначно определяется сочетанием actor_id, session_id и path. Один и тот же путь под двумя разными сессиями или под одной сессией и без неё содержит две отдельные записи.

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

Возвращение

Восстановить память двумя способами:

  • Перечисляет записи для актора, по желанию отфильтрованные по session_id, path префиксу или точному path. Используйте это, чтобы просматривать или отображать индекс того, что агент знает.
  • Ищите записи об актёре с помощью запроса на естественном языке. Поиск возвращает наиболее релевантные записи, ранжированные по показателю релевантности.

Фильтр session_id в любой из двух операций возвращает только те записи, сохранённые в этой сессии. Он не возвращает записи, сохранённые без сессии.

Get started

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

AgentKit SDK

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

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

    pip install databricks-agentbricks

  2. Создайте хранилище памяти для вашего агента. AgentKitClient Аутентифицируется с вашими WorkspaceClient учетными данными:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
memory_store = client.memory_stores.create("support-agent-memory")

  3. Сохраняйте память после того, как агент узнает что-то устойчивое о пользователе. actor_id — чья память это есть, path организует её внутри этого актора и description улучшает извлечение:

    memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
    description="User 123 communication preferences",
)

    add() завершается с ошибкой ALREADY_EXISTS, если запись уже существует по этому пути. Чтобы создать запись или обновить существующую, вызовите memory_store.put() с теми же аргументами.

  4. Вспомните воспоминания пользователя в последующем разговоре с помощью поиска на естественном языке:

    results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

API REST

Клиенты вызывают REST API под /api/2.0/agents/memory-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/memory-stores?managed_memory_store_id=support-agent-memory" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"description": "Support agent memory"}'

  3. Сохраните запись памяти для пользователя. actor_id — чья память это есть, path организует её и description улучшает восстановление:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "path": "/preferences/communication.md", "content": "Prefers email over phone.", "description": "Communication preferences"}'

    Если запись уже существует по этому пути, запрос завершается ошибкой ALREADY_EXISTS (HTTP 409). Чтобы обновить существующую запись, найдите её по пути. Запрос возвращает записи пути для каждой сессии, так что выбирайте тот, чей session_id совпадает. Последний сегмент его name — это идентификатор записи:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  --data-urlencode "actor_id=user-123" --data-urlencode "path=/preferences/communication.md"

    Затем обновите содержимое записи по её ID:

    curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries/<entry-id>?update_mask=content" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"content": "Prefers email over phone. Timezone: PST."}'

  4. Вспомните воспоминания пользователя с помощью поиска на естественном языке:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores/support-agent-memory/entries:search" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "user-123", "query": "communication preferences"}'

Дайте агенту инструменты памяти

Чтобы агент мог решать, когда сохранять и отзывать память, оберните клиентские операции как инструменты и дайте указания агенту, когда их использовать в системной подсказке. Установите actor_id в коде доверенного приложения на основе проверенных идентификационных данных конечного пользователя. Никогда не позволяйте модели выбирать, чью память читать или записывать.

Следующий пример оборачивает AgentKit SDK memory_store из раздела Начало работы в виде инструментов для OpenAI Agents SDK.

from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences, recall them when relevant, and forget them when the user asks.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

put() создаёт запись или заменяет содержимое записи, уже существующей по этому пути. Чтобы добавить контент в виде новых строк, вместо этого передайте append=True. put() не является атомарным, поэтому параллельные записи на один и тот же путь могут перезаписывать друг друга. list(path=...) возвращает записи по этому точному пути в каждой сессии, поэтому forget_memory также удаляет любую запись, сохранённую по этому пути в рамках сессии.

Та же схема работает с Claude Agent SDK и другими фреймворками: оберните операции поиска, записи, получения списка и удаления хранилища в тип инструмента фреймворка.

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

Раздел и защищённая память

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

  • Приватная память для каждого пользователя: Установите actor_id на проверенную идентификацию конечного пользователя. Каждый пользователь получает свой отдельный раздел, и агент вспоминает только записи этого пользователя.
    • Пример: Агент поддержки запоминает предпочтения пользователя в коммуникации и прошлые заявки.
  • Общая память для группы: Установите actor_id на выбранный вами фиксированный ключ, например, ID команды, проекта или организации. Все читают и пишут одни и те же воспоминания.
    • Пример: Агент команды запоминает общий глоссарий терминов компании и внутренних конвенций.
  • Разделение памяти по другому признаку: Создайте actor_id на основе собственных значений, таких как идентификатор арендатора или составной объект user:project.
    • Пример: Мультитенантное приложение устанавливает actor_id в значение {tenant}:{user}, чтобы пользователи каждого клиента оставались изолированными друг от друга.

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

Предупреждение

actor_id разделяет области памяти, но не является средством контроля доступа. Хранилища памяти ограничены рабочим пространством, поэтому любой принципал, имеющий доступ к хранилищу, может читать и записывать каждую запись во всех акторах. Магазин, а не актёр, — это граница безопасности. Для строгой изоляции между арендаторами или пользователями создайте отдельное хранилище памяти для каждой границы.

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

Limitations

  • Память агента предоставляет только долгосрочную память. Сведения о краткосрочной истории разговоров см. в сессиях агента.
  • Поиск ранжирует записи по релевантности, сочетая полнотекстовый поиск (BM25) и семантическое сопоставление по содержанию и описанию каждой записи. Он возвращает до 100 записей и не поддерживает пагинацию.
  • Контроль доступа осуществляется на уровне магазина. Контроль доступа за вход и для каждого участника недоступен.
  • Контроль доступа к магазину распространяется на входы в магазин. Любой пользователь рабочего пространства может просматривать и получать хранилища Memory, включая их идентификаторы и описания.
  • Вы не можете изменить ID магазина после его создания. Можно обновить только description.

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

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