Part 4 · Event Layer & UI Integration

The only interface between the agent runtime and your UI is the Transport. This part bridges the agent event stream to any UI shape (CLI, web, native mobile, background batch).

Key terms in this Part

• Transport — push interface (emit / ask_confirmation / ask_user / bailout); the only seam between runtime and your UI · §4.1, G.2
• AgentEvent — internal event types (text chunk, tool started/completed, LLM call) — debug only, not stable across releases · §4.2, G.6
• HostEvent — Pydantic-typed lifecycle event (tool / permission / subagent); stable, with schema snapshots · §4.7, G.1
• agent.events() — async pull iterator on the stable agentao.host surface; use for audit / SIEM / billing · §4.7
• agent.astream() — stable way to stream a turn's assistant text: TextDelta items, then the TurnOutcome; deltas are for display, the outcome is the answer · §4.4, §4.7
• active_permissions() — JSON-safe snapshot of the effective policy; use for "who can do what" UIs · §4.7, G.5

Coverage

• 4.1 Transport Protocol — Four methods, three implementation paths, threading and async rules
• 4.2 AgentEvent Reference — UI, tool, LLM, replay, and state-change events
• 4.3 SdkTransport Bridging — Best practices and pitfalls for the official callback bridge
• 4.4 Streaming UI — agent.astream() for text, plus end-to-end SSE and WebSocket examples
• 4.5 Tool Confirmation UI — CLI, web modal, mobile, unattended patterns
• 4.6 Max-Iterations Fallback — Five strategies + "stuck agent" detection heuristics
• 4.7 Embedded Harness Contract — agent.events() + active_permissions() + astream() — the stable host API for production audit / observability pipelines and streamed text
• 4.8 Orchestration Continuation — build a long-task "goal" loop (objective + time/turn budget) from the harness's drive-turn / inject-context / inject-tool primitives; /goal is the worked example

Before you start

• 2.2 Constructor Reference — semantics of the transport parameter
• 2.3 Lifecycle — chat() blocking semantics

Read by task

What you are building	Recommended path	You should be able to
Stream agent output into a web or app UI	4.4 → 4.7 → 4.1 → 4.3	Stream the answer text with astream(), and choose a Transport shape only for reasoning and raw tool output
Build tool confirmation, approval, or human-in-the-loop flows	4.1 → 4.5 → 5.4	Separate UI confirmation, permission rules, and unattended policy
Feed audit, billing, or SIEM pipelines	4.7 → 6.6	Use stable HostEvent data instead of internal AgentEvent details
Look up an event field or debug UI state	4.2 → 4.7	Know which events are for debugging and which APIs are production-safe
Prevent stuck agents or infinite loops	4.6 → 2.6	Design max-iteration, timeout, and fallback behavior

Mental model

Transport is your "UI spokesperson" — the agent interacts with the outside world only through it: emit events, ask for confirmation, ask the user, report bailouts. The stronger your Transport, the steadier your UX.

→ Start with 4.1 →