Streaming Events

AG-Kit uses an event-driven architecture to enable real-time communication between agents and frontend applications. This system provides structured, streaming capabilities for modern AI agent interactions.

Overview

The streaming event system is the core communication protocol that enables:

Real-time streaming of agent responses using Server-Sent Events (SSE)
Structured event handling for different types of interactions
Tool execution management with streaming parameters and results
State synchronization between agent and frontend
Error handling and lifecycle management

This provides a standardized way to handle real-time agent interactions.

Architecture Overview

Architecture Components

The AG-Kit streaming event system is designed with a modular architecture that supports:

Framework Adapters: Integration with popular AI frameworks (OpenAI, LangGraph, LangChain, Dify) and custom agents
Runtime Core: Central event processing system that handles all streaming events
Frontend Integration: Support for React, MiniProgram, Web Apps, and custom UI implementations
API Support: Multiple API protocols including REST, GraphQL, and WebSocket

Event Types

The streaming protocol categorizes events by their purpose:

Category	Description
Lifecycle Events	Monitor agent execution progress
Text Message Events	Handle streaming text content
Tool Call Events	Manage agent tool execution
State Management Events	Synchronize state between agent and UI
RESTful Support	Enable RESTful API access via headers

Server-Sent Events (Service → Client)

The RESTful API returns server-sent events with the following message types:

Event Type	Description
`data-ag-kit-response-init`	Initial response with thread and run IDs
`start`	Message start indicator
`text-start`	Text content start
`text-delta`	Text content delta
`text-end`	Text content end
`tool-input-start`	Tool input start
`tool-input-delta`	Tool input delta
`tool-input-available`	Tool input available
`tool-output-available`	Tool output available
`finish`	Response completion

Event Type Classification

Event Structure

All events share a common base structure with specific properties for each event type.

Base Event Properties

Property	Description
`type`	Specific event type identifier
`timestamp`	Optional timestamp when event was created
`rawEvent`	Optional field containing original event data before transformation

Event Structure Diagram

Lifecycle Events

Lifecycle events represent the execution lifecycle of an agent run. A typical agent run follows a predictable pattern: starting with a start event, potentially including multiple tool executions, and ending with a finish event.

Lifecycle Event Flow

Note: In the diagram above, event names use underscores (e.g., text_start) for Mermaid compatibility, but the actual event types use hyphens (e.g., text-start).

Start Event

Marks the beginning of an agent run. The start event is the first event emitted when an agent begins processing a request.

Property	Description
`type`	Always `"start"`
`messageId`	The message ID for this interaction

Finish Event

Marks the successful completion of an agent run. The finish event indicates that the agent has successfully completed all work for the current run.

Property	Description
`type`	Always `"finish"`

Text Message Events

Text message events represent the lifecycle of text messages in a conversation. Text message events follow a streaming pattern where content is delivered incrementally.

Text Message Streaming Flow

Text Message Start

Marks the beginning of a text message. The text-start event initializes a new text message in the conversation.

Property	Description
`type`	Always `"text-start"`
`id`	Unique identifier for the message

Text Message Delta

Represents a content chunk in a streaming text message. The text-delta event delivers incremental parts when message text becomes available.

Property	Description
`type`	Always `"text-delta"`
`id`	Matches the ID from `text-start`
`delta`	Text content chunk (non-empty)

Text Message End

Marks the end of a text message. The text-end event marks the completion of a streaming text message.

Property	Description
`type`	Always `"text-end"`
`id`	Matches the ID from `text-start`

Tool Call Events

Tool call events represent the lifecycle of tool calls made by the agent. Tool calls follow a streaming pattern similar to text messages.

Tool Call Execution Flow

Tool Input Start

Marks the beginning of a tool call. The tool-input-start event indicates that the agent is calling a tool to perform a specific function.

Property	Description
`type`	Always `"tool-input-start"`
`toolCallId`	Unique identifier for the tool call
`toolName`	Name of the tool being called

Tool Input Delta

Represents a parameter data chunk for a tool call. The tool-input-delta event delivers incremental parts when tool parameters become available.

Property	Description
`type`	Always `"tool-input-delta"`
`toolCallId`	Matches the ID from `tool-input-start`
`inputTextDelta`	Parameter data chunk

Tool Input Available

Marks the completion of tool parameter streaming. The tool-input-available event indicates that all parameters have been received and the tool can be executed.

Property	Description
`type`	Always `"tool-input-available"`
`toolCallId`	Matches the ID from `tool-input-start`
`toolName`	Name of the tool being called
`input`	Complete parameter data as string

Tool Output Available

Provides the result of tool call execution. The tool-output-available event delivers the output or result of a previously called tool.

Property	Description
`type`	Always `"tool-output-available"`
`toolCallId`	Matches the ID from the corresponding `tool-input-start` event
`output`	Actual result/output content from tool execution

State Management Events

State management events are used to manage and synchronize state between the agent and frontend.

State Management Architecture

Response Init Event

Provides initialization data for the agent response. The data-ag-kit-response-init event establishes the context for the current interaction.

Property	Description
`type`	Always `"data-ag-kit-response-init"`
`data`	Object containing initialization data
`data.threadId`	Unique thread identifier
`data.runId`	Optional run identifier

Event Flow Patterns

Events in the protocol typically follow specific patterns:

Start-Content-End Pattern: Used for streaming content (text messages, tool calls)
- Start event initiates the stream
- Content events deliver data chunks
- End event marks completion
Lifecycle Pattern: Used for monitoring agent execution
- Start event marks beginning
- Finish event marks completion

Event Flow Pattern Diagram

Implementation Considerations

When implementing event handlers:

Events should be processed in the order they are received
Events with the same ID (like messageId, toolCallId) belong to the same logical stream
Implementations should be resilient to out-of-order delivery
Custom events should follow established patterns for consistency

Implementation Best Practices

Complete Event Flow Example

Here’s a complete example of how events flow during a typical agent interaction:

Integration with AG-Kit

The streaming event system is deeply integrated into AG-Kit’s runtime:

Runtime Package: Core event mapping and streaming logic
Frontend Integration: Real-time UI updates based on events
Tool Execution: Seamless tool calling with streaming parameters
State Management: Automatic state synchronization

Runtime Integration

The runtime package (@ag-kit/runtime) provides:

Event mapping from internal message formats to streaming events
Streaming response handling using Server-Sent Events (SSE)
Tool execution coordination
State management utilities
RESTful API support via x-ag-kit-rest header

RESTful API Support

AG-Kit’s runtime provides RESTful API support through the useRestful() plugin. When a request includes the x-ag-kit-rest: true header, the system automatically:

Converts requests to RESTful format
Maps internal message formats to streaming events
Provides Server-Sent Events (SSE) responses
Handles tool execution and state management

Request Format

To use the RESTful API, include the following header in your request:

x-ag-kit-rest: true

The system will automatically detect this header and process the request through the RESTful pipeline, converting the response to the appropriate streaming event format.

Next Steps

Learn about Agent Invocation to see events in action
Explore Streaming Responses for real-time implementations
Review the Runtime API for implementation details

Technical Details

The streaming event system is compatible with the Vercel AI SDK’s streaming protocol (x-vercel-ai-ui-message-stream: v1), ensuring interoperability with existing AI application ecosystems.

TypeScript SDK

Python SDK

Headless UI Components

CLI Tools

​Streaming Events

​Overview

​Architecture Overview

​Architecture Components

​Event Types

​Server-Sent Events (Service → Client)

​Event Type Classification

​Event Structure

​Base Event Properties

​Event Structure Diagram

​Lifecycle Events

​Lifecycle Event Flow

​Start Event

​Finish Event

​Text Message Events

​Text Message Streaming Flow

​Text Message Start

​Text Message Delta

​Text Message End

​Tool Call Events

​Tool Call Execution Flow

​Tool Input Start

​Tool Input Delta

​Tool Input Available

​Tool Output Available

​State Management Events

​State Management Architecture

​Response Init Event

​Event Flow Patterns

​Event Flow Pattern Diagram

​Implementation Considerations

​Implementation Best Practices

​Complete Event Flow Example

​Integration with AG-Kit

​Runtime Integration

​RESTful API Support

​Request Format

​Next Steps

​Technical Details