Qwen-Code ACP与AG-UI协议深度解析：区别、场景与实战报文对比

在AI Agent开发、智能 Copilot、代码助手（Qwen-Code）落地过程中，绝大多数开发者都会混淆两个核心协议：ACP（Agent Client Protocol） 和AG-UI（Agent-User Interaction Protocol）。

很多人误以为二者是前端/后端的视角区别，或者是可随意替代的同类协议。实则不然，二者是内层进程通信、外层网络交互的分层协作关系，各司其职、部分场景可单用、Web端落地必须配合使用。

本文结合Qwen-Code架构，用通俗讲解+真实报文案例，彻底讲透两个协议的定位、区别、适用场景和工程落地逻辑。

一、核心定位一句话区分

1. ACP（Qwen-Code 自研协议）

进程内部IPC通信协议 ，基于JSON-RPC，默认通过子进程 stdin/stdout 传输，仅用于本地进程交互，不走网络。

核心作用：本地宿主程序 ↔ Qwen-Code qwen-acp 子进程双向通信，承载Agent核心运行、工具调用、流式输出等底层能力。

2. AG-UI（开源通用UI交互协议）

跨网络前端事件流协议 ，基于SSE/WebSocket，标准化UI交互事件，专为浏览器、前端页面设计。

核心作用：Web前端UI ↔ Agent后端服务流式交互，统一AI对话、工具调用、状态更新的前端渲染标准。

通俗类比

ACP：电脑主板内部总线（本机硬件内部通信）
AG-UI：对外网线接口（跨设备网络通信）

二者不是替代关系，是内外分层协作关系。

二、核心特性全方位对比

对比维度	ACP 协议	AG-UI 协议
协议归属	阿里Qwen-Code 自研私有协议	CopilotKit 开源通用标准协议
通信边界	本机进程间 IPC	跨设备网络通信
底层规范	JSON-RPC 2.0（请求-响应模型）	事件驱动流（SSE/WebSocket）
传输载体	子进程 stdin/stdout（无网络）	HTTP-SSE / WebSocket
适配端	IDE、本地脚本、SDK、本地CLI	浏览器、Web前端、Copilot组件
前端可用性	浏览器无法直接调用（沙盒隔离）	原生适配前端，可直接渲染UI
Qwen-Code适配	原生内置、核心依赖	无原生支持，需协议桥转换

三、实战报文示例（最直观理解）

1. ACP 协议真实报文（进程IPC）

场景：本地脚本调用 qwen-acp 子进程，下发代码生成指令，全程无HTTP、无浏览器。

客户端请求（宿主 → 子进程）

复制代码

{ "jsonrpc":"2.0", "id":1, "method":"agent.run", "params":{ "sessionId":"sess-001", "prompt":"写一个Python快速排序算法", "tools":["code_interpreter"] } }

子进程流式推送（增量内容）

复制代码

{ "jsonrpc":"2.0", "method":"agent.stream_chunk", "params":{ "sessionId":"sess-001", "content":"def quick_sort(arr):\n if len(arr) <= 1:\n return arr" } }

任务结束通知

复制代码

{ "jsonrpc":"2.0", "method":"agent.run_complete", "params":{"sessionId":"sess-001"} }

特点：标准JSON-RPC格式，有请求ID、方法名，纯进程内部数据传输。

2. AG-UI 协议真实报文（前端网络流）

场景：浏览器前端通过SSE订阅Agent响应，直接适配UI渲染，无需解析复杂RPC逻辑。AG-UI定义了标准化的生命周期、文本消息、工具调用三类核心事件。

SSE流式事件响应片段

复制代码

event: RUN_STARTED data: {"runId":"run-abc123"} event: TEXT_MESSAGE_START data: {"messageId":"msg-001","role":"assistant"} event: TEXT_MESSAGE_CONTENT data: {"content":"def quick_sort(arr):","messageId":"msg-001"} event: TOOL_CALL_START data: {"toolName":"code_interpreter","runId":"run-abc123","toolCallId":"tool-001"} event: TEXT_MESSAGE_END data: {"messageId":"msg-001","stopReason":"finish"} event: RUN_FINISHED data: {"runId":"run-abc123"}

特点：基于事件驱动，细分完整交互生命周期，前端可直接监听对应事件，完成打字流、工具弹窗、加载状态渲染。

四、核心疑问：能不能只使用其中一个？

很多开发者的核心困惑：两个协议功能相似，是否可以二选一、不用全部接入？答案：分场景，不能无条件互替。

场景1：只用ACP，完全不用AG-UI（可行）

适用场景：无Web前端，纯本地AI能力调用

VS Code IDE本地代码助手
本地CLI脚本、批量任务处理
桌面客户端、本地SDK调用

架构链路：本地程序 → ACP(stdio) → qwen-acp子进程

无需HTTP、无需前端、无需AG-UI协议转换，轻量化、无额外开销。

场景2：只用AG-UI，完全不用ACP（可行）

适用场景：Web端Agent服务，无子进程隔离架构

自研轻量AI对话网页
Agent逻辑与HTTP服务同进程运行
无需进程隔离、崩溃容错的简单场景

架构链路：浏览器 → AG-UI(SSE) → 后端Agent服务（同进程）

场景3：两个协议必须同时使用（Qwen-Code Web落地标准方案）

如果想要同时拥有 Qwen-Code子进程隔离能力 + Web前端可视化交互，二者缺一不可。

完整链路：

浏览器前端（AG-UI事件流） → 协议转换桥（AG-UI↔ACP） → ACP进程通信 → qwen-acp子进程 → Agent核心逻辑

核心原因：

浏览器无法直接访问本地子进程stdio，不能直接调用ACP；
qwen-acp子进程仅识别ACP JSON-RPC报文，不认识AG-UI前端事件；
必须通过桥接层完成网络事件 ↔ 进程RPC消息双向转换。

五、工程设计核心价值总结

ACP 核心价值

进程隔离：Agent运行在独立子进程，崩溃不影响主服务，稳定性更强；
内核复用：一套Agent核心代码，支持本地CLI、IDE、Web多形态部署；
低开销：基于stdio通信，无HTTP网络开销，本地调用效率极高。

AG-UI 核心价值

前端标准化：统一AI Agent流式交互规范，适配所有前端UI框架；
交互精细化：拆分加载、打字、工具调用、结束、异常全生命周期事件；
跨平台通用：开源通用标准，不绑定Qwen-Code，可适配任意AI Agent后端。

六、最终极简总结

不是前后端视角区别，是「进程内部通信」和「跨设备网络通信」的层级区别；
本地落地选ACP：IDE、本地脚本、离线任务，单用ACP足够；
轻量化Web落地选AG-UI：无进程隔离需求，单用AG-UI简洁高效；
企业级Web+Qwen-Code落地：双协议配合+协议桥接，兼顾稳定性和前端交互体验。

七、拓展学习

区分三个极易混淆的AI协议：

MCP：Agent ↔ 外部工具服务通信协议；
ACP：宿主服务 ↔ 本地Agent子进程通信协议；
AG-UI：Web前端 ↔ Agent后端网络交互协议