如何适配外部 Agent 的接口、事件和工具调用差异？

核心回答

外部Agent适配不只是换模型接口，还要统一会话生命周期、消息内容、事件流、工具状态、权限交互和产物交付。一种可落地设计是定义内部Agent接口和事件模型，每个外部系统实现适配器：向外转换请求，向内归一化结果，同时保留无法无损映射的原始字段与能力差异。

以接入OpenCode等编码Agent为设计示例，业务层发起任务、订阅进度、取消或恢复会话；适配器负责对应SDK、进程或协议。业务层不需要到处判断某家事件名，也不能假定每家都支持相同的工具与恢复能力。

适配接口与能力

会话接口要区分创建、继续、取消和关闭；映射外部session与内部task/run，绑定工作目录、模型配置和权限。能力表说明是否支持流式、附件、恢复、工具审批和并发，缺少的能力显式降级，不能用空实现假装成功。

消息适配处理文本、图片、文件引用和结构化产物，保留角色与关联关系。长文件不要塞进每个事件，使用受控产物引用；错误则区分参数、认证、限流、运行失败和结果未知，以便上层决定重试或终止。

事件与工具怎样映射

内部可以区分文本增量、工具提案、工具开始、进度、结果、权限请求、任务结束和错误。每条事件携带会话、run、调用ID和顺序信息，不能把每个文本分片误认为完整消息。

ACP v1用session/update报告工具调用与增量状态，工具有独立调用ID；OpenCode SDK提供SSE事件订阅。这些是可参考的实际差异：一个终态快照、一个文本delta、一个权限请求有不同语义，不能统一成“打印字符串”。流式参数应在完整解析和校验后交给真正执行方。

还要明确谁执行工具。外部Agent若已在自己的Runtime执行，适配层只观察回执，不能再执行一次；若由本地宿主执行，就要完成校验、权限与结果回传。权限请求和拒绝需要原样保持含义，不能把“等待批准”映射成“失败后自动重试”。

怎样验证适配器

用固定事件序列测试分片、乱序、重复、断线、取消后迟到和部分失败；再跑一条读文件、修改、测试、产物返回的实际任务。保留原事件到内部事件的关联，方便定位外部成功但内部未结束等问题。协议升级时按版本维护映射，未知事件可记录，不能静默丢掉可能影响状态的内容。

对应教程

参考资料