主题
云服务与 AI Framework 对接
本文关注接入方式，而不是强制框架改写。相关规范映射可参考 Control Plane API、Runtime Session Protocol、MCP Mapping 和 A2A Mapping。
接入原则
一个成熟的 AaaS 平台不应该要求团队放弃现有云服务和 AI Framework。更合理的策略是把现有系统收敛到四个稳定接口层：
资源注册- 把现有 Agent、Tool、执行画像和元数据注册到控制面
运行桥接- 把现有 runtime 或任务执行器接到 Runtime Session Gateway
事件映射- 把框架内部产生的消息、步骤、工具调用和工件转换成标准输出事件
观测导出- 把框架内部的步骤、模型调用和错误信息映射到统一 Trace / Span 模型
只要一个现有系统能在这四层落地，它就不必重写成平台私有框架。
对接现有云服务的常见接缝
身份、配置与 Secret
- 使用平台控制面保存 Agent 元数据和执行画像
- 继续复用现有云 Secret Manager、KMS、环境配置中心
- 在运行期通过 Session 协议按需取 Secret 和 Config，而不是把凭证硬编码进镜像
存储与状态
- 文件、Artifact、大型输出继续落在对象存储
- 中间恢复点以
Checkpoint形式纳管 - 临时键值和小型会话状态通过 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 - 把人工介入点映射到继续执行命令，而不是框架私有暂停协议
这样做的好处是：
- 继续保留 LangGraph 的图状态表达能力
- 平台层仍然统一管理 Run、Artifact、Trace 和工具治理
- 未来切换到其他图框架时，外部控制面和读面无需重写
OpenHands 一类 coding runtime 的对接方式
OpenHands 这类 coding agent runtime 更适合以“托管运行时”方式接入：
- 每个任务仍由平台创建
Run - 平台为任务准备 Sandbox 会话、文件系统和工具权限
- OpenHands 进程作为 runtime attach 到 Session
- 其内部的 shell、文件编辑、测试执行、浏览器操作映射到平台事件和 Span
- 工作区快照、补丁、日志和中间结果映射为 Artifact 或 Checkpoint
这种方式特别适合“平台想统一治理多个 coding agent，但不想改动它们内部 loop” 的场景。
如何兼容 MCP、A2A、AG-UI
这些协议更适合作为平台的北向或侧向适配层：
MCP- 适合表达 Tool 目录和 Tool 调用
A2A- 适合作为 Agent 卡片、任务创建与跨 Agent 协作协议
AG-UI- 适合作为前端交互和流式输出 transport
推荐做法不是让每个框架分别实现全部协议，而是让平台统一收口：
- 外部协议只映射到平台控制面和事件流
- Framework 只需要适配一套 Runtime Session 与 Trace Export 合约
一个最小接入清单
要把现有云服务或 AI Framework 接入 AaaS，通常需要完成下面几件事：
- 明确 Agent 资源如何注册，以及 execution profile 如何选择
- 明确 runtime 如何 attach、heartbeat、读取 config 和 secret
- 明确框架内部的消息、工具调用、工件和中间状态如何映射
- 明确失败、取消、超时和重试如何映射到 Run / Attempt 语义
- 明确如何导出 Trace、日志和关键指标
落地建议
- 优先做“边界适配”，不要先做“框架重写”
- 优先统一观测和生命周期，再逐步统一工具与策略
- 优先让平台接住失败和恢复，再做更复杂的多框架编排