Important
此功能在 Beta 版中。 要使用它,工作区管理员必须从预览页面开启代理内存会话。 请参阅 Manage Azure Databricks 预览版。
代理会话为你的代理提供了一个持久且与框架无关的会话状态存储:即代理或框架在一次交互中保存的状态。 最常见的是对话历史,即代理在回合开始时读取并附加的消息、工具调用和结果的有序转录。 它也可以是框架为该交互持久保存的任何其他状态,例如 LangGraph 图。 Azure Databricks 会把数据存储在 Lakebase 里,并帮你管理存储,所以你不需要自己构建或操作数据库。
注释
在预览阶段,你将为存储你的会话数据的底层 Lakebase 实例付费。 代理会话本身不需额外收费。 随着预览的推进,定价可能会有所调整。
当你想要执行以下操作时,请使用智能体会话:
- 坚持保留代理的对话历史,使其能在重启时存活并稍后继续。
- 重建后续信息的完整上下文(包括工具调用和推理)。
- 在你自己的界面中列出、继续和分支过往对话。
代理会话保持单次交互状态(短期的会话中状态)。 对于 跨越对话 持续的长期记忆,可以使用 代理记忆。
要求
- 安装 Python 3.10 或更高版本,以使用 AgentKit SDK。 AgentKit SDK 是 Databricks Python 代理 API 客户端,下面的示例就是用它。 你也可以直接从任何语言调用 REST API,无需 Python 要求。
- 要使用 REST API 示例,请安装 Databricks CLI(用于生成 OAuth 令牌)、
curl和jq。
代理会话的工作原理
代理会话有三个层级:
-
会话存储是限定在工作区内、用于存放代理会话的容器。 创建存储库时,系统会自动为底层的 Lakebase 存储预配资源。 你选择一个工作区独一无二的商店ID,并在后续调用中用它来指代商店。 将店铺ID传递为:
- AgentKit SDK 中的
name参数。 -
session_store_idREST API 中的查询参数。
- AgentKit SDK 中的
-
会话是商店内一次持久的交互(通常是对话线程)。 会话的标识方式如下:
-
actor_id(必填):会话所属者,如终端用户或其他代理。 它会把一个主题的所有会话分组,这样你可以把它们一起列出和筛选。 当你构建每个用户的应用时,设置actor_id用户ID(例如,通过应用认证验证的最终用户身份),这样每个用户的会话都会保持分组。 从可信的应用上下文中设置,绝不要用模型或用户提供的值。 -
session_id(可选):由调用方为该交互选择的 ID。 如果你省略该值,服务会自动生成一个。 -
parent_session_id(可选):将会话设置为存储中另一个会话的子节点,例如子代理的对话。 创建会话时设置。
-
-
会话项目是会话排序历史中的一个条目。 每个项都包含一个不透明的、兼容
dataJSON 的值,例如消息、工具调用、工具结果或推理块。 Azure Databricks 会为每个项目分配 anitem_id和 acreate_time,并且不检查或验证其内容。 附加后,物品不可更改。
该服务维护会话项目的确定性排序,并授权针对会话存储的每项操作。
开始
这些示例为支持坐席设置坐席会话:它们创建会话存储,为一次对话启动会话,添加对话的回合,并在后续请求时回读历史记录。 选择最适合你项目的客户。
商店ID在工作区内是唯一的。 如果你同时运行两个标签页,或者 ID 已经被占用,选择不同的 ID,或者先删除现有的存储。 存储响应还包含服务分配的 UUIDsession_store_id。 后续调用使用你选择的店铺 ID。
AgentKit SDK
AgentKit SDK 是 Databricks Python 客户端,用于代理 API,分发在包中databricks-agentbricks。 它通过Databricks SDK WorkspaceClient进行认证。
安装 AgentKit SDK:
pip install databricks-agentbricks该
databricks-agentbricks软件包提供了databricks_agentkitPython 模块。创建一个会话存储,然后针对一次对话启动一个会话。
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-sdk") session = session_store.add(actor_id="customer-123", session_id="case-456")在客服奔跑时,补充对话的轮流。 每个项都是任意 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."}, ] )在后续请求中,重新加载会话并阅读其完整历史以重建上下文:
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")]
REST API
客户端在 /api/2.0/agents/session-stores 下调用 REST API。 对于Python以外的语言,直接调用它。
将
DATABRICKS_HOST设置为你的工作区 URL,包括https://,然后使用 Databricks CLI 生成一个 OAuth 令牌:export DATABRICKS_HOST=https://<workspace-url> databricks auth login --host ${DATABRICKS_HOST} export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)为您的经纪人创建一个会话商店:
curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_id=support-agent-sessions-rest" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \ -d '{"description": "Support agent conversation history"}'为一次对话启动会话。
actor_id是它所属的对象;session_id唯一标识了这段对话:curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions?session_id=case-456" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \ -d '{"actor_id": "customer-123"}'在代理运行时,添加对话回合:
curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/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."}}]}'按时间顺序回溯阅读历史,以重建背景:
curl -G "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"响应返回
session_items中的项目,每个请求最多返回page_size个(默认 10,最大 100)。 如果还有更多项目,则包含next_page_token。 将该值传递为page_token,重复直到响应没有next_page_token。 AgentKit SDK 的list_items会为你处理分页。例如,这个循环一次读取完整的历史记录,100项:
PAGE_TOKEN="" while true; do RESPONSE=$(curl -s -G "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \ --data-urlencode "order_by=create_time asc" --data-urlencode "page_size=100" \ ${PAGE_TOKEN:+--data-urlencode "page_token=${PAGE_TOKEN}"}) echo "${RESPONSE}" | jq -c '.session_items[]?.data' PAGE_TOKEN=$(echo "${RESPONSE}" | jq -r '.next_page_token // empty') [ -z "${PAGE_TOKEN}" ] && break done
客户端还支持删除最近的项目、清除会话中的项目,以及将对话分叉成独立副本(可选择最多特定项目)。 分叉没有父会话,删除源会话也不会将其删除。 删除会话总是会删除其子会话及其项目。
使用智能体会话支持 Agent Framework 的会话
像 OpenAI Agents SDK 和 Claude Agent SDK 这样的代理框架,在运行开始时读取对话历史,并在结束时添加新项目。 会话存储直接映射到该模式:
| 框架操作 | AgentKit SDK 调用 |
|---|---|
| 阅读历史 | list_items(order_by="create_time asc") |
| 添加回合物品 | append_items(items) |
| 撤销最后一项 | pop_item() |
| 清除线程 | clear_items() |
范围与访问
代理会话将会话的项目存储为不透明、兼容 JSON 的值:服务会持久化保存并返回你的代理或框架附加的内容,而不会解释它。 它不会将执行控制资源(如运行、检查点或审批)作为一类概念添加,尽管一个序列化此类状态的框架可以将其作为项持久化。
会话存储限定在工作区范围内,且访问是在存储级别进行授权的。 存储访问控制涵盖存储的会话。 任何工作区用户都可以列出并获取会话存储,包括它们的ID和描述。
actor_id and metadata 字段仅支持分组和过滤;它们不授予或限制访问权限。 根据受信任的应用程序上下文设置 actor_id,而不是根据模型或用户提供的值。
若要让另一个主体(例如智能体的服务主体)使用存储,请通过存储的授予权限操作(AgentKit SDK 中的 session_store.grant_permission(principal_id))向其授予访问权限。 只有商店的创建者或工作区管理员可以授权访问。 请参阅 管理代理内存和会话存储的权限,了解权限级别、支持操作及示例。
代理会话和 代理内存 是独立的。 删除会话或会话存储并不会删除存储中保留的内存。 要从存储中的会话构建长期记忆,请创建记忆管道。