托管智能体内存

Important

此功能在 Beta 版中。

托管代理记忆为你的代理提供了持久且长期的记忆，这种记忆能在对话中持续存在。 Azure Databricks 将内存存储在 Lakebase 中，并帮你管理存储、索引和语义搜索，这样你的代理就能记住用户偏好、过去的决策和积累的上下文，而无需你操作数据库。

注释

在预览阶段，系统会就用于存储记忆条目的底层 Lakebase 实例向你收费。管理代理内存本身不需额外收费。随着预览的推进，定价可能会有所调整。

当你希望你的代理执行以下操作时，请使用托管内存：

在不同对话之间记住用户偏好、事实和决策。
根据客服在之前的会谈中学到的内容，个性化回答。
在经纪人和项目间分享积累的知识。
随着时间的推移提高准确性和效率。

托管内存适用于基于任何框架的代理。在单次交互中获取短期对话历史，可以使用托管代理会话。

Requirements

安装 Python 3.10 或更高版本，以使用 AgentKit SDK。 AgentKit SDK 是 Databricks Python 代理 API 客户端，下面的示例就是用它。你也可以直接从任何语言调用 REST API，无需 Python 要求。

托管内存的工作原理

托管代理内存资源层级结构：内存存储包含许多内存条目，每个条目由actor_id、可选session_id和路径标识，并包含内容和描述。

托管内存有两个级别：

记忆存储是用于存放代理记忆的工作区级容器。创建存储库时，系统会自动为底层的 Lakebase 存储预配资源。你用它的 display_name名称来称呼商店。
记忆条目是存储库中的一个独立内容项。每个条目包含一个自由形式文本 content、用于检索的短文 description ，以及一组用于组织和划分的字段：
- actor_id （必需）：内存的归属，如终端用户或其他代理。
- session_id （可选）：记录内存捕获的会话，用于追踪和来源确认。对于未绑定到特定会话的记忆，请保持其为未设置。
- path（必填）：一种类似文件系统的路径，用于组织 Actor 内的条目，例如 /preferences/response-style.md。

一个条目由 session_id、path 和 actor_id 的组合唯一标识。

检索

内存检索有两种方式：

演员的列表 条目，可选地通过 session_id 或前 path 缀过滤。用它来浏览或渲染代理所知的索引。
使用自然语言查询搜索某位演员的条目。搜索会返回以全文相关性评分（BM25）排名的相关性最高的条目。

开始

这些例子为支持代理设置了管理内存：他们创建内存存储，保存用户的偏好，并在后续对话中调用。选择最适合你项目的客户。存储 display_name 容量必须为3到56个字符，以小写字母开头，以字母或数字结尾，且仅包含小写字母、数字和连字符。

AgentKit SDK

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

安装 AgentKit SDK：
```
pip install databricks-agentbricks
```

为你的代理人创建一个记忆存储。 AgentKitClient 使用你的 WorkspaceClient 凭据进行身份验证：

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

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

在智能体了解到关于用户的持久信息后，保存记忆。 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",
)

通过自然语言搜索，在后续对话中调取用户的记忆：

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

REST API

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

使用 Databricks CLI 生成 OAuth 令牌：

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

为你的代理人创建一个记忆存储：

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-stores" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"display_name": "support-agent-memory", "description": "Support agent memory"}'

为用户保存一个内存条目。 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"}'

通过自然语言搜索回忆用户的记忆：

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。绝不要让模型自己选择读写谁的内存。

以下示例将 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."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

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

同样的模式也适用于 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）搜索操作，返回前 N 个结果组成的结果集，最多包含 100 个条目。它不支持分页或向量相似性搜索。
门店层面执行访问控制。针对每个条目和每个参与者的访问控制不可用。
display_name商店创建后是不可更改的。只有 description 可以更新。

后续步骤

反馈

此页面是否有帮助？

上次更新时间为 2026-10-06