代理内存

Important

此功能在 Beta 版中。 要使用它,工作区管理员必须从预览页面开启代理内存会话。 请参阅 Manage Azure Databricks 预览版。

代理记忆赋予代理跨对话持续的长期记忆。 Azure Databricks 将内存存储在 Lakebase 中,并帮你管理存储、索引和搜索,这样你的代理就能记住用户偏好、过去的决策和积累的上下文,而无需你操作数据库。

注释

在预览阶段,系统会就用于存储记忆条目的底层 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 来标识商店,创建商店时选择这个 ID。
  • 记忆条目是存储库中的一个独立内容项。 每个条目包含一个自由形式文本 content、用于检索的短文 description ,以及一组用于组织和划分的字段:
    • actor_id (必需):内存的归属,如终端用户或其他代理。
    • session_id (可选):该内存所属的会话。 如果要让内存应用于该参与者的各个会话,请将其保留为未设置状态。
    • path(必填):一种类似文件系统的路径,用于组织 Actor 内的条目,例如 /preferences/response-style.md。

一个条目由 session_id、path 和 actor_id 的组合唯一标识。 同一路径在两个不同会话下,或在某个会话下或不在任何会话下,会包含两个独立的条目。

条目通过以下两种方式进入存储:你的智能体或应用程序直接写入条目,或者记忆管道从会话存储内的对话中提取这些条目。

检索

内存检索有两种方式:

  • 参与者的列表条目,可选择通过 session_id、path 前缀或确切的 path 来筛选。 用它来浏览或渲染代理所知的索引。
  • 使用自然语言查询搜索某位演员的条目。 搜索结果会返回按相关性评分排名的最相关条目。

任一操作的 session_id 过滤器只返回该会话中保存的条目。 它不会返回会话中未保存的条目。

开始

AgentKit SDK 和 REST API 示例为支持代理设置了代理内存:它们创建内存存储,保存用户的偏好,并在后续对话中取回该偏好。 Agent Bricks CLI 示例将内存存储连接到你用 CLI 构建和部署的代理。 选择最适合你项目的客户。 存储 ID 必须为 3 到 56 个字符,以小写字母开头,以字母或数字结尾,且仅包含小写字母、数字和连字符。

AgentKit SDK

AgentKit SDK 是 Databricks Python 客户端,用于代理 API,分发在包中databricks-agentbricks。 它通过Databricks SDK WorkspaceClient进行认证。

  1. 安装 AgentKit SDK:

    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)
    

REST API

客户端在 /api/2.0/agents/memory-stores 下调用 REST API。 对于Python以外的语言,直接调用它。

  1. 使用 Databricks CLI 生成 OAuth 令牌:

    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 最后一段是条目 ID:

    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"}'
    

Agent Bricks

如果你用 Agent Bricks CLI 构建代理,agentbricks init 会在 agent.toml 中声明一个内存存储。 agentbricks deploy 如果存储还不存在,就创建它,并授予部署代理访问该存储的权限。

选择一个路径:

  • 以空配置启动(大多数智能体):部署智能体。 agentbricks deploy 创建 agentbricks init 声明的内存存储。 要部署名为 my-agent的代理,请执行以下操作:

    agentbricks deploy my-agent
    
  • 从存储中已有的记忆开始:先创建存储,添加条目,然后将存储绑定到代理并部署。

    1. 要创建一个名为 my-agent-memory的商店,运行以下操作。 输出包含商店ID,这是一个与商店名称分开的生成标识符:

      agentbricks memory stores create --name my-agent-memory
      
    2. 要添加条目,运行以下操作,替换 <store-id> 为上一步的商店 ID:

      agentbricks memory entries create --store <store-id> --actor-id you@example.com \
        --path /preferences/style.md --content "Prefers Python and concise answers with code examples."
      
    3. 要绑定存储库并部署智能体,请运行以下命令。 agentbricks memory bind 在 agent.toml 中替换店名,并且 agentbricks deploy 按名称查找现有商店并使用它,而不是创建新的商店:

      agentbricks memory bind my-agent-memory
      agentbricks deploy my-agent
      

--path 是条目在存储中的密钥,而不是你机器上的文件。 --actor-id 是记忆所属的用户。 部署的代理使用已登录用户的邮箱作为行为者 ID,因此每个条目都要预填与代理聊天的用户邮箱。

在 Agent Bricks CLI 中,memory bind 和 agentbricks deploy 均通过其名称来引用存储库。 作用于单个存储的命令(如 memory entries create,)会使用生成的存储ID。

为你的智能体配备记忆工具

让代理决定何时保存和调用内存,将客户端操作包装为工具,并在系统提示符中指示代理何时使用。 根据经过验证的终端用户身份,在受信任的应用程序代码中设置 actor_id。 绝不要让模型自己选择读写谁的内存。

以下示例将 Get Start 中的 AgentKit SDK memory_store 包装为 OpenAI 代理 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,例如租户 ID 或 user:project 组合值。
    • 示例: 多租户应用将 actor_id 设置为 {tenant}:{user},从而使每个客户的用户彼此隔离。

在应用程序代码中,将 actor_id 设置为来自可信调用方上下文的值:对于按用户划分的内存,使用经验证的终端用户身份;对于共享内存,使用可信的团队或项目密钥。 绝不要让模特自己选择。 如果你的策略依赖于最终用户身份,那么对于未携带该身份的请求,应拒绝处理,而不是回退为使用共享的 actor_id。

Warning

actor_id 它会分离记忆,但不是访问控制。 内存存储是工作空间范围的,因此任何能够访问存储的主体都可以读取和写入跨所有 actor 的所有条目。 商店,而非演员,才是安全边界。 为了严格隔离租户或用户,每个边界创建一个独立的内存存储。

若要让另一个主体(例如智能体的服务主体)使用存储,请通过存储的授予权限操作(AgentKit SDK 中的 memory_store.grant_permission(principal_id))向其授予访问权限。 只有商店的创建者或工作区管理员可以授权访问。 请参阅“管理代理内存和会话存储的权限”,了解权限级别、支持操作及示例。

Limitations

  • 智能体记忆仅提供长期记忆。 关于短期对话历史记录,请参见智能体会话。
  • 搜索通过通过内容和描述的全文(BM25)和语义匹配,对条目进行相关性排序。 它最多返回100条条目,且不支持分页。
  • 门店层面执行访问控制。 针对每个条目和每个参与者的访问控制不可用。
  • 商店门禁控制涵盖商店的入口。 任何工作区用户可以列出并获取内存存储,包括它们的ID和描述。
  • 创建商店后你不能更改ID。 只有 description 可以更新。

后续步骤