智能体与用户交互协议(Agent-User Interaction Protocol,AG-UI)用于连接智能体和面向用户的应用。IaC Code 可以通过 HTTP 和服务器发送事件(Server-Sent Events,SSE)向 Web 控制台、聊天客户端、IDE 扩展等前端持续发送文本、思考过程、工具调用、Pipeline 步骤和待用户处理的交互。本文介绍 AG-UI 服务的启动和最小接入流程。
适用场景
AG-UI 适合需要实时展示智能体执行过程的用户界面。客户端不需要把所有事件混入一段文本,可以分别展示:
模型回复和思考过程。
工具名称、参数、执行进度和结果。
Pipeline 步骤和云资源方案。
权限请求、补充问题和候选方案选择。
一次运行的开始、完成、失败和取消状态。
IaC Code 的 AG-UI 服务是 A2A 执行内核的协议适配层:
AG-UI 客户端
↓ RunAgentInput / SSE
iac-code agui
↓ 本机 A2A
IaC Code Agent / Pipeline / 云 API
AG-UI 和 A2A 使用同一套智能体执行逻辑、模型配置、云身份和权限规则。构建面向用户的交互界面时选择 AG-UI;让另一个智能体或编排平台远程调用 IaC Code 时选择 A2A;集成 IDE 或编辑器的智能体会话时可以选择 ACP。
前提条件
已完成安装和配置 IaC Code。
已准备一个 IaC Code 可以访问的绝对工作目录。
前端或后端能够发送 HTTP POST 请求并持续读取 SSE。
任务需要查询或管理云资源时,已配置具有最小必要权限的阿里云身份。
跨主机部署时,已准备服务认证、反向代理和网络访问控制。
启动 AG-UI 服务
安装 AG-UI 可选依赖:
python -m pip install "iac-code[agui]"
在项目目录中启动服务:
iac-code agui --host 127.0.0.1 --port 41243
未设置 --a2a-url 时,AG-UI 服务会自动启动并管理一个仅监听本机回环地址的 A2A 子进程。通常不需要单独启动 A2A Server。
检查服务状态:
curl http://127.0.0.1:41243/health
预期结果:返回 status 为 ok、protocol 为 ag-ui 的 JSON 数据。
连接第一个客户端
安装 AG-UI JavaScript 客户端:
npm install @ag-ui/client
下面的示例使用标准 HttpAgent 发送消息,并输出流式文本、工具调用和 Pipeline 步骤:
import { HttpAgent, randomUUID } from "@ag-ui/client";
const agent = new HttpAgent({
url: "http://127.0.0.1:41243/",
threadId: randomUUID(),
});
const forwardedProps = {
iacCode: {
schemaVersion: 1,
rosInvocationId: randomUUID(),
cwd: process.cwd(),
runMode: "normal",
preferredLanguage: "zh-CN",
},
};
agent.messages.push({
id: randomUUID(),
role: "user",
content: "检查当前目录中的 ROS 模板,只输出问题和修改建议,不要修改文件。",
});
const subscriber = {
onTextMessageContentEvent({ event }) {
process.stdout.write(event.delta);
},
onToolCallStartEvent({ event }) {
console.log(`\n[tool] ${event.toolCallName}`);
},
onStepStartedEvent({ event }) {
console.log(`\n[step] ${event.stepName}`);
},
onRunErrorEvent({ event }) {
console.error(`\n${event.code}: ${event.message}`);
},
};
await agent.runAgent({ forwardedProps }, subscriber);
cwd 必须是绝对路径,并位于 AG-UI 服务允许访问的目录下。rosInvocationId 表示当前业务调用,同一次中断恢复必须保持不变。
预期结果:客户端依次收到运行开始、文本、工具或步骤事件,以及运行完成事件。普通 AG-UI 客户端可以忽略不认识的 IaC Code 自定义事件,不影响标准文本和运行状态处理。
管理多轮会话
一次用户输入对应一次新的 HTTP/SSE 请求。同一段对话复用 threadId,每次运行使用新的 runId;使用官方客户端时,runId 默认由客户端生成。
前一个请求完成后,可以向同一个 HttpAgent 的 messages 添加新消息并再次调用 runAgent()。不要在已经结束的 SSE 连接上继续发送下一轮消息。
启动 Pipeline
将 forwardedProps.iacCode.runMode 设置为 pipeline:
const forwardedProps = {
iacCode: {
schemaVersion: 1,
rosInvocationId: randomUUID(),
cwd: process.cwd(),
runMode: "pipeline",
pipelineName: "selling",
candidatePresentation: "rich",
},
};
客户端应处理标准的步骤、文本、思考、工具和活动快照事件。架构候选、资源栈进度等没有标准 AG-UI 对应项的信息,会通过 IaC Code 命名空间下的自定义事件发送。
处理中断和恢复
当 IaC Code 需要权限审批、补充信息或方案选择时,当前运行会以包含 interrupts 的 RUN_FINISHED 事件结束。客户端应执行以下操作:
根据每个中断的
message、responseSchema和选项渲染交互界面。收集所有待处理中断的用户回答,不替用户选择或默认批准写操作。
使用原
threadId、新的runId和原rosInvocationId发起新请求。通过标准
resume数组提交与responseSchema匹配的回答。
不同中断需要的回答结构可能不同。不要把权限的 decision 结构用于普通问题或候选方案选择。完整字段和示例请参见 AG-UI 协议参考。
配置生产环境访问
本地开发时优先绑定 127.0.0.1。跨主机提供服务时,至少设置访问令牌和允许的工作目录:
export IAC_CODE_AGUI_AUTH_TOKEN="${AGUI_SERVICE_TOKEN}"
export IAC_CODE_AGUI_ALLOWED_CWDS="/srv/iac-code-workspaces"
iac-code agui --host 0.0.0.0 --port 41243
客户端在请求中携带:
Authorization: Bearer <token>
生产部署还应遵循以下要求:
通过 Secret 管理方案提供令牌、模型凭据和阿里云身份,不写入配置文件或前端代码。
使用私网、防火墙或反向代理限制访问来源,并启用 TLS。
只允许具体的工作目录,不要把文件系统根目录加入
IAC_CODE_AGUI_ALLOWED_CWDS。AG-UI 适配器连接的 A2A 地址必须是本机回环地址,不能配置为任意远程 A2A 服务。
浏览器应用通常通过同源后端或反向代理访问;AG-UI 服务不会自动开放跨域访问。
为客户端设置取消、重连和超时边界,但不要把 SSE 心跳误判为业务事件。
常见问题
启动时提示缺少 AG-UI 依赖
确认使用运行 iac-code 的同一个 Python 环境安装了 iac-code[agui]。虚拟环境中安装后,应重新进入该环境再启动命令。
请求返回 401
确认服务端设置了预期的 IAC_CODE_AGUI_AUTH_TOKEN,客户端使用相同 Secret 发送 Authorization: Bearer <token>,并检查反向代理是否保留该请求头。
请求提示工作目录无效
forwardedProps.iacCode.cwd 必须是绝对路径,并位于 IAC_CODE_AGUI_ALLOWED_CWDS 或 A2A 允许目录下。同一个 threadId 不能在后续请求中切换到另一个工作目录。
新消息提示需要先恢复任务
当前线程仍有待处理的权限、问题或方案选择。客户端必须先展示并通过 resume 回答全部待处理中断,再发送下一条普通消息。
服务提示本地 A2A 不可用
未设置 --a2a-url 时,检查 AG-UI 进程是否有权限启动子进程以及端口是否可用。独立管理 A2A 时,确认 --a2a-url 指向本机回环地址,并检查双方配置的 A2A Token 是否一致。