代理会话

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_id REST API 中的查询参数。
  • 会话是商店内一次持久的交互(通常是对话线程)。 会话的标识方式如下:
    • actor_id (必填):会话所属者,如终端用户或其他代理。 它会把一个主题的所有会话分组,这样你可以把它们一起列出和筛选。 当你构建每个用户的应用时,设置 actor_id 用户ID(例如,通过应用认证验证的最终用户身份),这样每个用户的会话都会保持分组。 从可信的应用上下文中设置,绝不要用模型或用户提供的值。
    • session_id(可选):由调用方为该交互选择的 ID。 如果你省略该值,服务会自动生成一个。
    • parent_session_id (可选):将会话设置为存储中另一个会话的子节点,例如子代理的对话。 创建会话时设置。
  • 会话项目是会话排序历史中的一个条目。 每个项都包含一个不透明的、兼容 data JSON 的值,例如消息、工具调用、工具结果或推理块。 Azure Databricks 会为每个项目分配 an item_id 和 acreate_time,并且不检查或验证其内容。 附加后,物品不可更改。

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

开始

这些示例为支持坐席设置坐席会话:它们创建会话存储,为一次对话启动会话,添加对话的回合,并在后续请求时回读历史记录。 选择最适合你项目的客户。

商店ID在工作区内是唯一的。 如果你同时运行两个标签页,或者 ID 已经被占用,选择不同的 ID,或者先删除现有的存储。 存储响应还包含服务分配的 UUIDsession_store_id。 后续调用使用你选择的店铺 ID。

AgentKit SDK

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

  1. 安装 AgentKit SDK:

    pip install databricks-agentbricks
    

    该databricks-agentbricks软件包提供了 databricks_agentkit Python 模块。

  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-sdk")
    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_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)
    
  2. 为您的经纪人创建一个会话商店:

    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"}'
    
  3. 为一次对话启动会话。 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"}'
    
  4. 在代理运行时,添加对话回合:

    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."}}]}'
    
  5. 按时间顺序回溯阅读历史,以重建背景:

    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))向其授予访问权限。 只有商店的创建者或工作区管理员可以授权访问。 请参阅 管理代理内存和会话存储的权限,了解权限级别、支持操作及示例。

代理会话和 代理内存 是独立的。 删除会话或会话存储并不会删除存储中保留的内存。 要从存储中的会话构建长期记忆,请创建记忆管道。

后续步骤