Module 05: Streaming Updates

Receive real-time updates from an agent while it processes your prompt.

What You’ll Learn

Registering a sessionUpdateHandler on the client
Dispatching on SessionUpdate types with instanceof
Handling message chunks, thoughts, tool calls, and plans

The Code

The client registers an update consumer that receives each SessionUpdate as it arrives:

AcpSyncClient client = AcpClient.sync(transport)
    .sessionUpdateHandler(notification -> {
        handleSessionUpdate(notification.update());
    })
    .build();

The handler uses instanceof to dispatch on the SessionUpdate type:

private static void handleSessionUpdate(SessionUpdate update) {
    if (update instanceof AgentMessageChunk msg) {
        System.out.print(((TextContent) msg.content()).text());
    } else if (update instanceof AgentThoughtChunk thought) {
        System.out.println("[Thought] " +
            ((TextContent) thought.content()).text());
    } else if (update instanceof ToolCall tool) {
        System.out.println("[Tool] " + tool.title() +
            " (" + tool.status() + ")");
    } else if (update instanceof ToolCallUpdateNotification toolUpdate) {
        System.out.println("[Tool Update] " + toolUpdate.title() +
            " -> " + toolUpdate.status());
    } else if (update instanceof Plan plan) {
        System.out.println("[Plan] " + plan.entries().size() + " steps");
    } else if (update instanceof AvailableCommandsUpdate commands) {
        System.out.println("[Commands] " + commands.availableCommands().size() +
            " available");
    } else if (update instanceof CurrentModeUpdate mode) {
        System.out.println("[Mode] " + mode.currentModeId());
    } else if (update instanceof UsageUpdate usage) {
        System.out.println("[Usage] " + usage.used() + "/" + usage.size());
    }
}

Session Update Types

Type	Description
`AgentMessageChunk`	Incremental response text (the main output)
`AgentThoughtChunk`	Agent’s thinking process
`ToolCall`	Tool execution starting
`ToolCallUpdateNotification`	Tool progress update
`Plan`	Agent’s planned steps with priorities and status
`AvailableCommandsUpdate`	Slash commands the agent supports
`CurrentModeUpdate`	Agent mode change
`UsageUpdate`	Context window and cost usage

Updates arrive during client.prompt(). The prompt call blocks until the agent returns a PromptResponse, but updates stream in continuously through the consumer. As of 0.80.0, prompt() returns only after the consumer has finished handling every update from that turn. So by the time prompt() returns, whatever your consumer collected (printed text, counted tool calls, and so on) is already complete; there’s no need to wait or poll for trailing updates afterward.

Source Code

View on GitHub

Running the Example

Requires the Grok CLI on your PATH, signed in once with grok login. The module launches it as grok agent stdio; no API key is needed.

./mvnw exec:java -pl module-05-streaming-updates

Next Module

Module 12: Echo Agent — build your first ACP agent (no API key required).

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

05 streaming updates

Module 05: Streaming Updates

What You’ll Learn

The Code

Session Update Types

Source Code

Running the Example

Next Module

​Module 05: Streaming Updates

​What You’ll Learn

​The Code

​Session Update Types

​Source Code

​Running the Example

​Next Module

Module 05: Streaming Updates

What You’ll Learn

The Code

Session Update Types

Source Code

Running the Example

Next Module