第四部分 · 事件层与 UI 集成
Agent 运行时与你的用户界面之间的唯一接口就是 Transport。这部分教会你完整地把 Agent 的事件流桥接到任意 UI 形态（CLI / Web / 手机原生 / 后台批处理）。
本部分关键词
- Transport — 推送接口（
emit/ask_confirmation/ask_user/bailout）；运行时和 UI 之间的唯一缝隙 · §4.1、G.2 - AgentEvent — 内部事件类型（文本片段、工具启动/完成、LLM 调用）—— 仅供调试，版本间不保证稳定 · §4.2、G.6
- HostEvent — Pydantic 类型的生命周期事件（tool / permission / subagent）；稳定，附 schema 快照 · §4.7、G.1
agent.events()— 落在稳定agentao.host表面上的异步 pull 迭代器；审计 / SIEM / 计费用 · §4.7active_permissions()— 当前生效策略的 JSON 化快照，给"谁能做什么"UI 用 · §4.7、G.5
本部分覆盖
- 4.1 Transport Protocol — 四个方法、三种实现路径、线程与异步要点
- 4.2 AgentEvent 事件清单 — UI、工具、LLM、replay 与状态变更事件
- 4.3 SdkTransport 快速桥接 — 官方回调实现的最佳实践与陷阱
- 4.4 构建流式 UI — SSE / WebSocket 端到端示例
- 4.5 工具确认 UI — CLI / Web 模态 / 手机 / 批处理四种形态
- 4.6 最大迭代数兜底策略 — 五种策略 + 卡死检测启发式
- 4.7 嵌入式 Harness 合约 —
agent.events()+active_permissions()—— 给生产审计 / 可观测流水线用的稳定宿主 API
开始之前
- 2.2 构造器完整参数表 —
transport参数语义 - 2.3 生命周期管理 —
chat()的阻塞特性
按任务阅读
| 你要做什么 | 推荐路径 | 读完应能完成 |
|---|---|---|
| 把 Agent 输出流接进 Web / App UI | 4.1 → 4.3 → 4.4 | 选定 Transport 形态，把 token、工具状态和错误稳定推到前端 |
| 做工具确认、审批或人工介入 | 4.1 → 4.5 → 5.4 | 分清 UI 确认、权限规则和无人值守策略 |
| 接审计、计费或 SIEM 流水线 | 4.7 → 6.6 | 使用稳定 HostEvent，而不是依赖内部 AgentEvent |
| 查某个事件字段或调试 UI 状态 | 4.2 → 4.7 | 知道哪些事件可用于调试，哪些 API 可用于生产 |
| 避免 Agent 卡死或无限循环 | 4.6 → 2.6 | 设计最大轮次、超时和兜底回复 |
心智模型
Transport 是你的"UI 代言人"—— Agent 只通过它与外界发生任何互动： 推事件、问确认、反问用户、报告兜底。 你实现得越扎实，UI 体验就越稳。
→ 4.1 开始 →