受管理的代理会话

Important

此功能在 Beta 版中。

托管代理会话为你的代理提供了一个持久且与框架无关的会话状态存储：即代理或框架在一次交互中保持的状态。 最常见的是对话历史，即代理在回合开始时读取并附加的消息、工具调用和结果的有序转录。 它也可以是框架为该交互持久保存的任何其他状态，例如 LangGraph 图。 Azure Databricks 会把数据存储在 Lakebase 里，并帮你管理存储，所以你不需要自己构建或操作数据库。

注释

在预览阶段，你将为存储你的会话数据的底层 Lakebase 实例付费。 托管代理会话本身不需额外收费。 随着预览的推进，定价可能会有所调整。

当您想要使用托管会话时：

• 坚持保留代理的对话历史，使其能在重启时存活并稍后继续。
• 重建后续信息的完整上下文（包括工具调用和推理）。
• 在你自己的界面中列出、继续和分支过往对话。

托管会话保存单次交互的状态（短期的会话内状态）。 若要使用可跨对话持久保留的长期记忆，请使用托管式代理记忆。

要求

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

管理式会话的工作原理

托管课程分为三个层级：

• 会话存储是限定在工作区内、用于存放代理会话的容器。 创建存储库时，系统会自动为底层的 Lakebase 存储预配资源。 你选择一个在工作区内唯一的 session_store_name。
• 会话是商店内一次持久的交互（通常是对话线程）。 会话的标识方式如下：
  • actor_id （必填）：会话所属者，如终端用户或其他代理。 它会把一个主题的所有会话分组，这样你可以把它们一起列出和筛选。 当你构建每个用户的应用时，设置 actor_id 用户ID（例如，通过应用认证验证的最终用户身份），这样每个用户的会话都会保持分组。 从可信的应用上下文中设置，绝不要用模型或用户提供的值。
  • session_id（可选）：交互的由调用方选择的 ID。 如果你省略该值，服务会自动生成一个。
  • parent_session_id （可选）：将会话与其分支会话链接，以表示分支对话。
• 会话项目是会话排序历史中的一个条目。 每个项都包含一个不透明的、兼容 data JSON 的值，例如消息、工具调用、工具结果或推理块。 Azure Databricks 会为每个项目分配 an item_id 和 acreate_time，并且不检查或验证其内容。 附加后，物品不可更改。

该服务维护会话项目的确定性排序，并授权针对会话存储的每项操作。

开始

这些例子为支持代理设置托管会话：他们创建会话存储，为一次对话启动会话，添加对话的轮值，并在后续请求时回读历史记录。 选择最适合你项目的客户。

AgentKit SDK

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

1. 安装 AgentKit SDK：

   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")]
   

REST API

客户端在 /api/2.0/agents/session-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/session-stores?session_store_name=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"
   

客户端还支持删除最近的项目、清除会话中的项目，以及将对话分叉成独立副本（可选择最多特定项目）。 删除包含子会话的会话时，需要使用强制选项才能级联删除这些子会话（例如，session.delete(force=True)）。

使用托管会话存储智能体框架的会话

像 OpenAI Agents SDK 和 Claude Agent SDK 这样的代理框架，在运行开始时读取对话历史，并在结束时添加新项目。 会话存储直接映射到该模式：

框架操作	会话存储调用
阅读历史	list_items 按时间顺序排列（order_by="create_time asc"）
添加回合物品	append 新物品
撤销最后一项	pop 最近的项
清除线程	clear 会议内容

范围与访问

托管会话将会话中的条目存储为不透明且兼容 JSON 的值：服务会持久保存并返回你的代理或框架应用附加的任何内容，而不对其进行解释。 它不会将执行控制资源（如运行、检查点或审批）作为一类概念添加，尽管一个序列化此类状态的框架可以将其作为项持久化。

会话存储限定在工作区范围内，且访问是在存储级别进行授权的。 actor_id and metadata 字段仅支持分组和过滤;它们不授予或限制访问权限。 根据受信任的应用程序上下文设置 actor_id，而不是根据模型或用户提供的值。

若要让另一个主体（例如智能体的服务主体）使用存储，请通过存储的授予权限操作（AgentKit SDK 中的 session_store.grant_permission(principal_id)）向其授予访问权限。

托管会话和 托管内存 是独立的。 删除会话或会话存储并不会删除存储中保留的内存。

后续步骤

• 托管代理内存
• 代理API参考