Skip to content

云服务与 AI Framework 对接 ​

本文关注接入方式,而不是强制框架改写。相关规范可参考 Control Plane API、Runtime SDK、Runtime Connection Protocol、A2A Profile、ACP Profile、AG-UI Profile 和 MCP Server Profile。

接入原则 ​

一个成熟的 AaaS 平台不应该要求团队放弃现有云服务和 AI Framework。更合理的策略是把现有系统收敛到五个稳定接口层:

  • 资源注册
    • 把现有 Agent、Tool、MCP Server、Revision、ReleaseChannel、ProtocolBinding 和元数据注册到控制面
  • 运行桥接
    • 把现有 runtime 或任务执行器接到 Runtime Connection Gateway
  • 事件映射
    • 把框架内部产生的消息、步骤、工具调用和工件转换成标准输出事件
  • 观测导出
    • 把框架内部的步骤、模型调用和错误信息映射到统一 Trace / Span 模型
  • 协议对齐
    • 把现有系统需要暴露给外部生态的 A2A、ACP、AG-UI、MCP 能力映射到平台定义的 protocol profiles 与 protocol bindings

只要一个现有系统能在这五层落地,它就不必重写成平台私有框架。

对接现有云服务的常见接缝 ​

身份、配置与 Secret ​

  • 使用平台控制面保存 Agent 元数据和执行画像
  • 继续复用现有云 Secret Manager、KMS、环境配置中心
  • 在运行期通过 Runtime Connection 协议按需取 Secret 和 Config,而不是把凭证硬编码进镜像

存储与状态 ​

  • 文件、Artifact、大型输出继续落在对象存储
  • 中间恢复点以 Checkpoint 形式纳管
  • 临时键值和小型会话状态通过 Runtime Connection API 暴露的 Session KV 提供统一能力

消息与异步触发 ​

  • 队列、Event Bus、Webhook 仍然由现有云服务承载
  • 但进入平台后要映射到统一的 Run 创建、继续执行或工具调用事件

网络与安全 ​

  • VPC、出口控制、域名白名单、审计代理继续由云基础设施处理
  • 平台只要求这些能力能够与 Agent 身份、Run 身份和执行画像关联

对接 AI Framework 的推荐模式 ​

模式一:Framework 作为 Runtime 内核 ​

这适合已经有完整 Agent 循环、规划器和工具调用机制的框架。接入时保留其内部逻辑,只在边界层适配:

  • 框架实例映射为某个 Agent 的 runtime 实现
  • 框架的一次任务执行映射为 Run
  • 框架内部步骤映射为 Span
  • 框架输出消息、工具调用、工件映射为标准输出事件

模式二:Framework 作为编排子系统 ​

如果框架擅长工作流、图执行或多阶段规划,也可以只把它当作 Agent 内部的一段执行引擎:

  • 平台仍然拥有 Run 生命周期
  • Framework 只负责 Agent 内部计划和步骤执行
  • 外部观察面和恢复语义仍回到平台标准模型

模式三:Framework 作为 Tool Fabric ​

如果已有系统只想把某些高级能力暴露给 Agent,例如搜索、浏览器、知识检索或代码分析,可把框架包装成平台 Tool,而不是整体接管运行时。

常见系统的接入速览 ​

现有系统类型典型例子推荐接入角色平台重点接管的边界
图工作流框架LangGraphruntime 内核或编排子系统Run 生命周期、Checkpoint、Trace、人工继续执行
coding agent runtimeOpenHands 一类 runtime托管 runtimeSandbox、Session、Artifact、审计与恢复
自研 Agent 服务业务内部 orchestration service运行桥接层attach、heartbeat、事件映射、错误归一化
能力型子系统搜索、浏览器、知识检索、代码分析服务Tool FabricTool 身份、配额、权限、限流和观测

LangGraph 的对接方式 ​

LangGraph 更适合以“有状态执行图”视角接入 AaaS。推荐做法是:

  • 把一个 LangGraph 应用注册为某个 Agent 或某类 Agent 的 runtime
  • 把图执行的一次 invocation 映射为 Run
  • 把图中的 node、edge 跳转、条件分支和子图执行映射到 Span
  • 把 graph state 的持久化快照映射到 Checkpoint
  • 把人工介入点映射到 InteractionRequest 与继续执行命令,而不是框架私有暂停协议
  • 优先让图节点依赖 Core SDK,把文件系统、terminal、browser 一类强环境能力留在独立 Platform SDK
  • 由 worker、faas、sandbox 平台包通过 use(...) / register(...) 为 Core SDK 注入 polyfill,而不是要求图代码自己分支处理宿主差异
  • 如果某个 Agent 版本开始显式调用 Platform SDK,则由开发者发布新的 AgentRevision.executionProfile.executionClass.runEnv,而不是期待平台在运行中自动迁移

这样做的好处是:

  • 继续保留 LangGraph 的图状态表达能力
  • 平台层仍然统一管理 Run、Artifact、Trace 和工具治理
  • 同一份图逻辑只要仍停留在 Core SDK,就更容易在 worker、faas、sandbox 之间做版本化升级或降级
  • 未来切换到其他图框架时,外部控制面和读面无需重写

OpenHands 一类 coding runtime 的对接方式 ​

OpenHands 这类 coding agent runtime 更适合以“托管运行时”方式接入:

  • 每个任务仍由平台创建 Run
  • 平台为任务准备 Sandbox Session、文件系统和工具权限
  • OpenHands 进程作为 runtime attach 到平台,并绑定当前 Session
  • 其内部的 shell、文件编辑、测试执行、浏览器操作映射到平台事件和 Span
  • 工作区快照、补丁、日志和中间结果映射为 Artifact 或 Checkpoint

这种方式特别适合“平台想统一治理多个 coding agent,但不想改动它们内部 loop” 的场景。

如何兼容 MCP、A2A、ACP、AG-UI ​

这些协议更适合作为平台的北向或侧向原生协议面:

  • MCP
    • 适合把能力服务以 McpServer 形式暴露 tool catalog、prompts/resources 与托管 session
  • A2A
    • 适合作为 Agent 卡片、任务创建与跨 Agent 协作协议
  • ACP
    • 适合作为强会话客户端、coding tool 和 runtime 的会话协议
  • AG-UI
    • 适合作为前端交互和流式输出 transport

推荐做法不是让每个框架分别实现全部协议,而是让平台统一收口:

  • 外部协议统一映射到平台控制面、读面、interaction 模型和事件流
  • Framework 只需要适配一套 Runtime SDK、Runtime Connection 与 Trace Export 合约
  • 审批、补充输入、鉴权和确认统一收敛到 InteractionRequest

一个最小接入清单 ​

要把现有云服务或 AI Framework 接入 AaaS,通常需要完成下面几件事:

  1. 明确 Agent / Tool / MCP Server 身份、Revision、ReleaseChannel 如何注册,以及 execution profile 如何选择
  2. 明确 runtime 代码依赖的是 Core SDK 还是 Platform SDK,以及平台包需要注册哪些 core polyfill
  3. 明确 runtime 如何通过 Runtime Connection attach、heartbeat、读取 config 和 secret
  4. 明确框架内部的消息、工具调用、工件和中间状态如何映射
  5. 明确失败、取消、超时和重试如何映射到 Run / Attempt 语义
  6. 明确审批、补充输入、鉴权如何映射到 InteractionRequest
  7. 明确如何导出 Trace、日志和关键指标

落地建议 ​

  • 优先做“边界适配”,不要先做“框架重写”
  • 优先统一观测和生命周期,再逐步统一工具与策略
  • 优先让平台接住失败和恢复,再做更复杂的多框架编排

相关规范 ​

白皮书与规范内容以仓库真源为准。