Stream Protocol
Convert public Harness observations into typed AG-UI events for terminals, browsers, and transports.
Stream Protocol (a13n-stream-protocol) only converts events: it does not run an Agent or provide an SSE server.
Start here
| Task | Guide |
|---|---|
| Run a complete conversion without credentials | Getting started |
| Map text, reasoning, tools, custom events, and terminal results | Events and processors |
| Rebuild a projection after a consumer restart | Replay and recovery |
| Look up public exports, fragment limits, and payload shapes | API and payload reference |
| Continue Agent execution from saved state | Harness State and Resume |
One observer, one Run
HarnessAguiObserver binds to one Run. HarnessAguiStreamObserver instead binds to a root stream and tracks its inline children independently, attributing their output with subagentRunId. Host-managed asynchronous child Runs still use independent observers.
observe() returns only events produced by the current item. snapshot() returns detached accumulated events; it is an in-memory convenience, not a durable log. resume() reconstructs observer state from exact Harness source history without publishing history again.
Install
uv add a13n-stream-protocolPublished Stream Protocol pins the matching Harness release. The source quickstart uses the repository lockfile to match this documentation on main.
Ownership Summary
| Concern | Owner |
|---|---|
Harness execution, source lifecycle, result, and HarnessState | Harness |
| Harness-to-AG-UI conversion and process-local reconstruction | Stream Protocol |
| Visibility policy expressed by a replay-stable processor | Host processor |
| Source-history retention, cursor, gap detection, and live cutover | Host |
| Durable AG-UI IDs, persistence, replay, and fan-out | Host |
| SSE, WebSocket, Redis, or in-process delivery | Host transport |
| Rendered view state | Renderer |
Upgrade to AG-UI 1.0
Upgrade Hosts and renderers together. Python uses ag-ui-protocol>=1,<2; browser consumers use upstream @ag-ui/core types and schemas, not a replacement transport client. Standard wire fields are camelCase. There is no 0.x decoder or alias layer.
- Logical Run start emits
RUN_STARTEDonce, after preparation and before public output. - Cancellation and suspension use
RUN_FINISHEDwith cancelled or interrupt outcomes; only failure usesRUN_ERROR. Deferred call IDs stay native, and Host answer validation is unchanged. - Input uses CUSTOM
value.event.roleandvalue.event.message_id, with top-level metadata. - Tool results may contain ordered upstream content parts; hidden supplemental media is never public. Binary data and unsafe URLs become payload-omitted descriptors, never inline bytes; provider file handles stay
FileSourcereferences without a downloadable URL. - Namespace inline child display keys by
subagentRunId. Child replies do not become root answers. Missing historical child display cannot be reconstructed from model history.
This protocol upgrade does not discard Harness continuation state or usage ledgers.
Next Steps
- Read the Harness guide for building, streaming, and resuming Agents.
- Read the package README for package and release details.
- Consult the Stream Protocol specification for the normative observation contract and schema boundary.
Reference topics
| Topic | Guide |
|---|---|
| Observe a Harness Run | Observe a Harness Run |
| Read the Accumulated Snapshot | Read the Accumulated Snapshot |
| Apply a Host Processor | Apply a Host Processor |
| Resume from Source History | Resume from Source History |
| Resume Is Not Agent Recovery | Resume Is Not Agent Recovery |
| Errors and Atomicity | Errors and Atomicity |