第四部分 · 事件层与 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.7
agent.astream() — 流式输出一轮 assistant 文本的稳定方式：先产出 TextDelta，最后是 TurnOutcome；增量用于显示，结果以 outcome 为准 · §4.4、§4.7
active_permissions() — 当前生效策略的 JSON 化快照，给"谁能做什么"UI 用 · §4.7、G.5

本部分覆盖

4.1 Transport Protocol — 四个方法、三种实现路径、线程与异步要点
4.2 AgentEvent 事件清单 — UI、工具、LLM、replay 与状态变更事件
4.3 SdkTransport 快速桥接 — 官方回调实现的最佳实践与陷阱
4.4 构建流式 UI — 文本用 agent.astream()，外加 SSE / WebSocket 端到端示例
4.5 工具确认 UI — CLI / Web 模态 / 手机 / 批处理四种形态
4.6 最大迭代数兜底策略 — 五种策略 + 卡死检测启发式
4.7 嵌入式 Harness 合约 — agent.events() + active_permissions() + astream() —— 给生产审计 / 可观测流水线和流式文本用的稳定宿主 API
4.8 编排续航 — 用 harness 的驱动一轮 / 注入上下文 / 注入工具原语,搭建长任务"goal"循环(目标 + 时间/轮次预算);/goal 即范例

你要做什么	推荐路径	读完应能完成
把 Agent 输出流接进 Web / App UI	4.4 → 4.7 → 4.1 → 4.3	用 `astream()` 流式输出回答文本，只为 reasoning 和原始工具输出选定 Transport 形态
做工具确认、审批或人工介入	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 体验就越稳。