Message & Event

Message and event are the two fundamental data structures in AgentScope.

Message — the primitive of agent-to-agent communication and persistence. Each Msg is a complete conversation turn, stored in the context and passed between agents.
Event — the primitive of frontend interaction and streaming. Events carry incremental progress updates (text tokens, tool-call fragments, permission requests, …) and drive real-time UIs and human-in-the-loop flows.

The event sequence emitted by a single call always condenses into exactly one assistant Msg, ensuring the full message state can be reconstructed from the event stream alone.

Message

Msg (io.agentscope.core.message) represents one turn of conversation — a user input, an agent reply, or a system instruction — with content modelled as an ordered list of typed ContentBlocks.

A single assistant Msg corresponds to one full call cycle (multiple reasoning + acting iterations until the final reply).

Structure

The core fields on Msg (via getters):

Method	Type	Description
`getId()`	`String`	Unique message identifier
`getName()`	`String`	Sender name (nullable)
`getRole()`	`MsgRole`	`USER` / `ASSISTANT` / `SYSTEM` / `TOOL`
`getContent()`	`List<ContentBlock>`	Ordered list of content blocks (immutable)
`getMetadata()`	`Map<String, Object>`	Arbitrary key/value metadata
`getTimestamp()`	`String`	Creation time (`yyyy-MM-dd HH:mm:ss.SSS`)
`getUsage()`	`ChatUsage`	Token usage (assistant messages only)
`getGenerateReason()`	`GenerateReason`	Termination reason: `MODEL_STOP` / `TOOL_SUSPENDED` / `REASONING_STOP_REQUESTED` / `ACTING_STOP_REQUESTED` / `ALL_TOOLS_DENIED` / `INTERRUPTED` / `MAX_ITERATIONS`

Content blocks

Message content is composed of typed blocks, each representing one type of information. Block classes live in io.agentscope.core.message:

Block	Description	Allowed in
`TextBlock`	Plain text content	USER, ASSISTANT, SYSTEM
`DataBlock`	Binary data (image / audio / video) via base64 or URL — unifies the legacy ImageBlock / AudioBlock / VideoBlock	USER, ASSISTANT
`ImageBlock` / `AudioBlock` / `VideoBlock`	Legacy concrete media blocks (still supported; new code should prefer `DataBlock`)	USER
`ThinkingBlock`	Model reasoning / chain of thought	ASSISTANT
`ToolUseBlock`	A tool call: `id` / `name` / `input` / `state` (`ToolCallState`)	ASSISTANT
`ToolResultBlock`	A tool result with `state` (`ToolResultState`)	ASSISTANT
`HintBlock`	Instructions injected into the loop as user context	ASSISTANT

Role constraints are enforced at construction: USER only allows text/data/image/audio/video blocks; SYSTEM only allows TextBlock; ASSISTANT allows all block types.

Creating a message

The role-pinned subclasses (io.agentscope.core.message.UserMessage / AssistantMessage / SystemMessage / ToolResultMessage) provide convenient constructors. When content is a plain string, it is wrapped in a TextBlock automatically.

import io.agentscope.core.message.AssistantMessage;
import io.agentscope.core.message.Base64Source;
import io.agentscope.core.message.DataBlock;
import io.agentscope.core.message.SystemMessage;
import io.agentscope.core.message.TextBlock;
import io.agentscope.core.message.UserMessage;

// User message — text only
UserMessage userText = new UserMessage("user", "What's in this image?");

// Multi-modal user message
UserMessage userMulti =
        new UserMessage(
                "user",
                TextBlock.builder().text("Describe this image:").build(),
                DataBlock.builder()
                        .source(Base64Source.builder()
                                .data("...")
                                .mediaType("image/png")
                                .build())
                        .build());

// System message — text only
SystemMessage systemMsg = new SystemMessage("system", "You are a helpful assistant.");

// Assistant message — all block types allowed
AssistantMessage assistantMsg = new AssistantMessage("agent", "Here's the result...");

For more optional fields (metadata, timestamp, usage, generateReason), use each subclass’s builder():

UserMessage msg =
        UserMessage.builder()
                .name("user")
                .textContent("Hello")
                .build();

Accessing content

Msg provides helpers for extracting specific block types:

Method	Returns
`getTextContent()`	All `TextBlock`s concatenated by `\n`; empty string when there are none
`getContentBlocks(Class<T>)`	List filtered by type
`getFirstContentBlock(Class<T>)`	The first matching block, or null
`hasContentBlocks(Class<T>)`	`true` if a block of the given type exists

import io.agentscope.core.message.ToolUseBlock;
import io.agentscope.core.message.ToolResultBlock;

// All text content
String text = msg.getTextContent();

// All tool calls
List<ToolUseBlock> toolCalls = msg.getContentBlocks(ToolUseBlock.class);

// Whether there are tool results
if (msg.hasContentBlocks(ToolResultBlock.class)) {
    // ...
}

Event

Events are the streaming counterpart of messages. While the agent runs, it emits a sequence of AgentEvents (io.agentscope.core.event) representing incremental progress — text tokens arriving, tool calls being assembled, results streaming back. Each event is lightweight and self-contained.

Event lifecycle

Every event carries getReplyId(), tying it to the message being assembled. Within a reply, getBlockId() or getToolCallId() acts as a correlation key for events that belong to the same content-block lifecycle. Events follow a start → delta → end pattern: All events in one reply share the same replyId. Within a reply, blockId ties text/thinking/data block events together; toolCallId ties tool calls and tool results. A blockId is scoped to its replyId and does not have to be a globally unique generated ID. When a block type can have at most one lifecycle within a reply, an implementation may use a stable type key, such as a fixed key for the text block.

Event types

All events extend AgentEvent (io.agentscope.core.event), which exposes the common methods:

Method	Type	Description
`getId()`	`String`	Unique event identifier
`getCreatedAt()`	`String`	ISO 8601 timestamp
`getType()`	`AgentEventType`	Event type enum
`getSource()`	`String`	Source path identifying the originating agent. `null` for top-level agent events; a slash-separated path (e.g. `"main/researcher"`) for events forwarded from a subagent
`getMetadata()`	`Map<String, Object>`	Optional key/value bag. Remote subagent forwards also set `taskId` (`AgentEvent.METADATA_TASK_ID`) to the harness / Agent Protocol task id and `parentSessionId` (`AgentEvent.METADATA_PARENT_SESSION_ID`) to the parent session when events are task-backed

Events are grouped below; unless noted otherwise, every event also carries getReplyId() linking it to the message being assembled.

Lifecycle events

AgentStartEvent — agent begins a new reply.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getSessionId()`	`String`	Session ID
`getName()`	`String`	Agent name
`getRole()`	`String`	Agent role (default `"assistant"`)

AgentEndEvent — agent finishes a reply.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID

ExceedMaxItersEvent — agent hit the max reasoning-acting iteration limit.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID

RequestStopEvent — early-stop request raised by middleware or a tool.

Text streaming events

TextBlockStartEvent — a new text block begins.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getBlockId()`	`String`	Text-block correlation key within the current reply

TextBlockDeltaEvent — incremental text content arrives.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getBlockId()`	`String`	Text-block correlation key within the current reply
`getDelta()`	`String`	Incremental text content

TextBlockEndEvent — text block completes.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getBlockId()`	`String`	Text-block correlation key within the current reply

Thinking streaming events

ThinkingBlockStartEvent / ThinkingBlockDeltaEvent / ThinkingBlockEndEvent — same shape as the text streaming events; specific to the model’s chain of thought. Its blockId has the same reply-scoped correlation-key semantics.

Data streaming events

DataBlockStartEvent / DataBlockDeltaEvent / DataBlockEndEvent — same shape as the text streaming events, carrying images / audio / video binary data:

DataBlockStartEvent: getMediaType() returns the MIME type (e.g. "image/png").
DataBlockDeltaEvent: getData() returns incremental base64-encoded data.

Tool-call streaming events

ToolCallStartEvent — agent begins a tool call.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getToolCallId()`	`String`	Unique tool call ID
`getToolCallName()`	`String`	The tool being called

ToolCallDeltaEvent — incremental tool-call arguments arrive; getDelta() returns a JSON fragment.ToolCallEndEvent — tool-call arguments complete.

Tool-result streaming events

ToolResultStartEvent — tool starts executing (carries toolCallId, toolCallName).ToolProgressEvent — an intermediate update published by a running tool through ToolEmitter. Progress is for display only and is never sent to the LLM; it must not be treated as part of the tool result.ToolResultTextDeltaEvent — incremental text output from the tool’s return value; getDelta() returns a text fragment. This is what the LLM receives as the tool result.ToolResultDataDeltaEvent — incremental binary or structured output from the tool’s return value; similar to DataBlockDeltaEvent with mediaType / data / url.ToolResultEndEvent — tool completes.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getToolCallId()`	`String`	The matching tool call ID
`getState()`	`ToolResultState`	Final state: `SUCCESS`, `ERROR`, `INTERRUPTED`, `DENIED`, `RUNNING`, `SUSPENDED`

Model-call events

ModelCallStartEvent — model API call starts (carries modelName).ModelCallEndEvent — model API call completes (carries inputTokens / outputTokens).

Human-in-the-loop events

RequireUserConfirmEvent — agent pauses for user confirmation.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getToolCalls()`	`List<ToolUseBlock>`	Tool calls awaiting confirmation

RequireExternalExecutionEvent — agent pauses for external execution. A suspended call produces no ToolResult* events: the tool has not executed, and the real result is supplied by the caller and surfaced through ExternalExecutionResultEvent.

Method	Type	Description
`getReplyId()`	`String`	Reply message ID
`getToolCalls()`	`List<ToolUseBlock>`	Tool calls awaiting external execution

UserConfirmResultEvent — emitted when a later call() resumes a paused permission HITL request. It carries one or more ConfirmResults, and its replyId matches the earlier RequireUserConfirmEvent.

Method	Type	Description
`getReplyId()`	`String`	Reply ID of the correlated `RequireUserConfirmEvent`
`getConfirmResults()`	`List<ConfirmResult>`	Confirmation results accepted for this resume

ExternalExecutionResultEvent — emitted when a later call() resumes a paused external-execution request. It carries one or more ToolResultBlocks, and its replyId matches the earlier RequireExternalExecutionEvent.

Method	Type	Description
`getReplyId()`	`String`	Reply ID of the correlated `RequireExternalExecutionEvent`
`getToolResults()`	`List<ToolResultBlock>`	External execution results accepted for this resume

AllToolsDeniedEvent — the user denied all tool calls from the most recent reasoning step via HITL confirmation. This event is emitted through the onActing middleware chain, allowing middlewares to emit a RequestStopEvent to stop the agent. If no middleware handles it, the agent continues to the next reasoning iteration (backward compatible).

Method	Type	Description
`getDeniedToolCalls()`	`List<ToolUseBlock>`	The denied tool calls

Subagent events

SubagentExposedEvent — a subagent spawned via agent_spawn(expose_to_user=true) has been exposed as a user-addressable entry point. SSE / streaming consumers can use this to render a new conversation entry in the UI.

Method	Type	Description
`getSubagentId()`	`String`	Unique identifier of the subagent
`getAgentId()`	`String`	Agent type ID of the subagent
`getSessionId()`	`String`	Session ID of the subagent
`getLabel()`	`String`	User-visible label (optional)

Reconstructing messages from events

Events and messages are not separate worlds — they are two views of the same data. The event stream from streamEvents can be aggregated by replyId / blockId / toolCallId to reconstruct a complete AssistantMessage, ensuring the final message state is fully recoverable from events alone. See agentscope-core’s agent/StreamingHook.java and agentscope-examples/documentation/.../streaming/AgentEventStreamExample.java for the standard pattern of grouping by block ID and accumulating content with Reactor operators.

import io.agentscope.core.event.AgentEvent;
import io.agentscope.core.event.AgentStartEvent;
import io.agentscope.core.event.AgentEndEvent;
import io.agentscope.core.event.TextBlockDeltaEvent;
import io.agentscope.core.event.ToolCallStartEvent;
import io.agentscope.core.event.ToolResultEndEvent;

StringBuilder accumulated = new StringBuilder();

agent.streamEvents(userMsg)
        .doOnNext(event -> {
            if (event instanceof AgentStartEvent start) {
                System.out.println("[start replyId=" + start.getReplyId() + "]");
            } else if (event instanceof TextBlockDeltaEvent delta) {
                accumulated.append(delta.getDelta());
            } else if (event instanceof ToolCallStartEvent tc) {
                System.out.println("[tool] " + tc.getToolCallName());
            } else if (event instanceof ToolResultEndEvent end) {
                System.out.println("[tool result state=" + end.getState() + "]");
            } else if (event instanceof AgentEndEvent end) {
                System.out.println("\n[end] full text:\n" + accumulated);
            }
        })
        .blockLast();

For live output within the current request, adapt AgentEvent to SSE. streamEvents() starts execution and has no durable cursor; do not execute the request again to catch up after a disconnect. Harness also saves logs for direct calls by default. See Session operations, events and recovery for reading history and introducing AgentSession when you need background tasks. Hosted frontends use Agent API snapshot plus SSE.

Example: streaming UI

A typical streaming UI loop (a Spring WebFlux SSE form is shown in streaming/StreamingWebExample.java):

import io.agentscope.core.event.AgentEndEvent;
import io.agentscope.core.event.AgentStartEvent;
import io.agentscope.core.event.TextBlockDeltaEvent;
import io.agentscope.core.event.ToolCallStartEvent;
import io.agentscope.core.event.ToolResultEndEvent;
import io.agentscope.core.message.UserMessage;

agent.streamEvents(new UserMessage("user", "Help me fix this bug"))
        .doOnNext(event -> {
            if (event instanceof AgentStartEvent start) {
                System.out.println("[start replyId=" + start.getReplyId() + "]");
            } else if (event instanceof TextBlockDeltaEvent delta) {
                System.out.print(delta.getDelta());
            } else if (event instanceof ToolCallStartEvent tc) {
                System.out.println("\n[calling " + tc.getToolCallName() + "...]");
            } else if (event instanceof ToolResultEndEvent end) {
                System.out.println("[tool finished: " + end.getState() + "]");
            } else if (event instanceof AgentEndEvent end) {
                System.out.println("\n[done]");
            }
        })
        .blockLast();

Agent

How agents emit events and messages in the ReAct loop

Context

How messages are stored and persisted

Relationship to durable SessionEvent

AgentEvent is a typed live event; SessionEvent is an immutable durable fact, not a one-to-one copy. Standard execution exposes agentId/sessionId/turnId/runId through event.getExecution(). runId matches native executionRunId. Forwarded children keep their own identity. Live event IDs, native seq and public SSE cursors remain independent; receiving a live event is not a commit acknowledgment. A logical turn may span multiple executions. AgentEndEvent only ends the current invocation. See Session operations, events and recovery.

Quick Start

Building Blocks

Harness

Reference

Message

Structure

Content blocks

Creating a message

Accessing content

Event

Event lifecycle

Event types

Reconstructing messages from events

Example: streaming UI

Further reading

Agent

Context

Relationship to durable SessionEvent

​Message

​Structure

​Content blocks

​Creating a message

​Accessing content

​Event

​Event lifecycle

​Event types

​Reconstructing messages from events

​Example: streaming UI

​Further reading

Agent

Context

​Relationship to durable SessionEvent

Message

Structure

Content blocks

Creating a message

Accessing content

Event

Event lifecycle

Event types

Reconstructing messages from events

Example: streaming UI

Further reading

Relationship to durable SessionEvent