云服务与 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，而不是整体接管运行时。

常见系统的接入速览

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

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、日志和关键指标

落地建议

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

相关规范

• Runtime SDK
• Runtime Connection Protocol
• Runtime Tracing
• Trace Export