Agent UI Protocol

Transport-neutral event schemas and state helpers for rendering realtime agent sessions.

Install

npm install @agent/agent-ui-protocol zod

zod is a peer dependency because the package exports Zod schemas.

Usage

import { UIEvent, emptySession, reduce } from '@agent/agent-ui-protocol';

let session = emptySession('session-1');
const event = UIEvent.parse({ type: 'turn_start', turn_id: 'turn-1' });
session = reduce(session, event).next;

Protocol

The package exports these protocol primitives:

• UIEvent: Zod discriminated union for all realtime events.
• InteractionRequestData and InteractionResponseData: request and response schemas for user/tool interactions.
• SessionHistory: persisted history schema for non-streaming hydration.
• AgentTransport: transport interface for clients.
• MockTransport: deterministic in-memory transport for demos and tests.

Realtime event types:

• session_event
• turn_start
• turn_end
• part_add
• part_update
• part_complete
• tool_input_delta
• tool_input_complete
• tool_result
• session_error
• compact_start
• compact_end
• interaction_request

State helpers:

• emptySession(id)
• hydrate(history)
• reduce(session, event)
• applyOptimisticUserMessage(session, id, text)
• confirmOptimisticUserMessage(session, id)
• rollbackOptimisticUserMessage(session, id)

Development

bun run test
bun run typecheck
bun run build
npm pack --dry-run