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
• 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 — 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() — the stable host API for production audit / observability pipelines

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.1 → 4.3 → 4.4	Choose a Transport shape and push tokens, tool states, and errors to the frontend
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 →