LangChain Managed Deep Agents 0.8 实操：用 HTTP channels 让 Agent 接收任意 webhook

# 项目结构
# my-agent/
#   agent.py
#   channels/
#     orders.py        # 本篇的主角
#   lib/
#     orders.py        # verify 与 parse 的实现放这里

# channels/orders.py
from managed_deepagents import channels
from lib.orders import parse, verify

channel = channels.http(
    provider="orders",   # 外部服务命名，给调用方 ID 做命名空间
    verify=verify,       # 鉴权回调
    parse=parse,         # 请求转消息回调
)

声明即注册：provider 名只要是任意非空名称即可，声明这个动作本身就把 provider 登记进系统了。工程上有两条约定值得养成：文件名即通道名，起名前想清楚这个端点对外是什么语义；provider 按外部服务聚合——同一个 Shopify 服务拆成订单、退款两个通道时，两边都声明 provider: "shopify"，调用方凭据就自然归一到同一个主体，不用重复授权。一个项目可以声明多个 HTTP channel，名称之间不得重复。

# lib/orders.py
import hashlib
import hmac
import os
from managed_deepagents import HttpChannelRequest

def verify(context: HttpChannelRequest) -> bool:
    secret = os.environ["ORDERS_WEBHOOK_SECRET"]
    digest = hmac.new(secret.encode(),
                      context.raw_body,
                      hashlib.sha256).hexdigest()
    received = context.request.headers.get("x-orders-signature", "")
    return hmac.compare_digest(f"sha256={digest}", received)

这段官方参考实现浓缩了三条 webhook 安全的基本功：对原始字节算签名（context.raw_body），因为任何框架层的 body 重解析都可能改变序列化结果；用恒定时间比较（hmac.compare_digest）防时序侧信道；密钥从环境解析而不是硬编码。官方还有一条容易踩的坑提示：通道凭据要从环境变量解析，不要用 connections.get——那个接口需要一次运行上下文，在 verify 阶段还没有运行。verify 可以是 async 函数；返回 False 的请求收到 401，抛异常的请求收到 500，两种都算拒绝。

# lib/orders.py（承接上面的导入）
import json
import uuid

# thread_id 必须是 UUID：用 uuid5 把外部会话 ID
# 稳定映射成 UUID，同一会话永远映射到同一线程
ORDERS_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_URL,
                              "https://orders.example.com")

def parse(context: HttpChannelRequest):
    payload = json.loads(context.raw_body)
    if payload.get("action") not in ("recheck", "summarize"):
        return {"type": "ignore"}   # 不关心的事件直接跳过
    return {
        "type": "message",
        "message": {
            # 调用方在外部系统的 ID（字符串），
            # Agent Auth 据此解析可用凭据的主体
            "user_id": str(payload["user_id"]),
            # 会话 UUID：同值续同一段对话
            "thread_id": str(uuid.uuid5(
                ORDERS_NAMESPACE, str(payload["conversation_id"]))),
            # 回复目的地（与 agent 线程分开存），
            # 即使通道只启动运行也要带上
            "target": {"channel": payload["channel"]},
            # 触发本次运行的消息文本
            "content": payload["text"],
        },
    }

parse 的返回只有两种形态：消息形态启动运行，{"type": "ignore"} 跳过事件。四个必填字段的语义要逐个吃透：user_id 必须从已验证的数据推导（别信未经校验的字段），数字 ID 记得 str() 转换；thread_id 是全篇最硬的约束——必须是 UUID，其他值一律 400，所以外部会话 ID 要先用 uuid5 做稳定映射，同一个外部会话每次都映射到同一个 UUID，对话才能续上；target 是你在 provider 侧的回复目的地，与 agent 线程 UUID 是两回事；content 是消息文本或 LangChain 内容块列表。字段与校验语义以官方文档为准，不同版本可能微调。

# 部署（CLI 会列出每个 HTTP channel 的 webhook URL）
mda deploy

# 部署输出示例（结构示意）：
#   channels/orders -> https://.../orders

# 把 URL 配到你的外部系统，
# 请求头带上签名（与 verify 对应）：
#   x-orders-signature: sha256=<hmac>

# 失败兜底：运行失败可发送默认错误回复，
# 或注册可选的 error callback 自定义行为

部署完成后，CLI 输出里会列出每个通道的 webhook URL——把它配置进你的订单系统、工单后台或任何能 POST JSON 的服务，记得同时配好签名头。0.8 的运行时对失败运行内置了兜底：可以发送默认错误回复，也可以挂自定义 error callback，避免「Agent 挂了但调用方毫无感知」。联调阶段建议用 mda chat（0.8.3 新增的终端客户端）先在本地把 Agent 本体跑顺，再接外部 webhook，把变量控制在一个维度上。

# memory.py
from managed_deepagents import MemoryLayer, define_memory

memory = define_memory(
    agent=MemoryLayer(),  # 共享层：挂载在 /memories/agent/
    user=MemoryLayer(),   # 隔离层：挂载在 /memories/user/
)                          # 按调用方身份为键

# 运行时行为：
#   - agent 记忆：全体用户共享（团队规则、流程）
#   - user 记忆：个人偏好、历史上下文，
#     其他用户不可见
#   - 运行时从不在两层之间复制内容

双层记忆是 0.8 的另一个主角，与 HTTP channels 组合刚好覆盖「自建系统里的多用户 Agent」场景：agent 层放团队级知识（升级流程、话术规范），user 层放个人偏好（某位客服喜欢简洁回复、某位客户的历史诉求）。关键设计是运行时不跨层复制内容——共享知识与个人上下文物理隔离，合规审查时能直接说清「谁的什么数据存在哪里」。还要记住通道感知的路由默认值：Slack 私聊两层都可见，Slack 群聊与 HTTP 请求默认只显 agent 记忆——这是为了防止群聊场景下的隐私泄漏，团队可以在策略里调整默认行为，但改之前想清楚你的调用方身份是否足够可信。

# 1) Agent 自有连接：免浏览器授权流
mda connections create --grant-type client_credentials

# 2) 沙箱文件 API（工具与中间件内）：
#    runtime.backend 支持 list/read/write/edit/
#    search/upload/download（Python: upload_files/
#    download_files）；未声明沙箱时 backend 不存在
#    注意：backend 不暴露 Context Hub 记忆与技能

# 3) 应用侧 prompt 的打断恢复：
#    用 INTERRUPT_CORRELATION_KEY + correlation_id
#    精确匹配到对应 interrupt；无关联 ID 时
#    仅恢复单个 pending 或开启新轮次

0.8 还有一批生产向的补充能力值得知道。凭据：OAuth 支持面扩到 23 个服务，agent 自有的 client_credentials 连接可以免浏览器授权流，由 MDA 直接获取 token；连接可以经 bearer/basic 包装后用于沙箱代理头，MDA 在每次命令前解析并跟随变更。文件：授权工具与中间件通过 runtime.backend 读写托管沙箱文件，二进制走 upload/download 接口；Slack 场景的入站文件自动存到 /workspace/attachments/。打断恢复：当应用通过 channel 主动发 prompt 并等待用户回答时，多个 pending interrupt 必须用 correlation_id 精确匹配——这是把 Agent 嵌进自有产品界面时最容易漏配的一环。