Events

The Agent Wire Protocol Python SDK uses a streaming event-based architecture. Events are the fundamental units of communication between agents and the frontend. This section documents the event types and their properties.

EventType Enum

from agentwire.core import EventType

The EventType enum defines all possible event types in the system:

class EventType(str, Enum):
    TEXT_MESSAGE_START = "TEXT_MESSAGE_START"
    TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT"
    TEXT_MESSAGE_END = "TEXT_MESSAGE_END"
    TOOL_CALL_START = "TOOL_CALL_START"
    TOOL_CALL_ARGS = "TOOL_CALL_ARGS"
    TOOL_CALL_END = "TOOL_CALL_END"
    STATE_SNAPSHOT = "STATE_SNAPSHOT"
    STATE_DELTA = "STATE_DELTA"
    MESSAGES_SNAPSHOT = "MESSAGES_SNAPSHOT"
    RAW = "RAW"
    CUSTOM = "CUSTOM"
    RUN_STARTED = "RUN_STARTED"
    RUN_FINISHED = "RUN_FINISHED"
    RUN_ERROR = "RUN_ERROR"
    STEP_STARTED = "STEP_STARTED"
    STEP_FINISHED = "STEP_FINISHED"

BaseEvent

from agentwire.core import BaseEvent

All events inherit from the BaseEvent class, which provides common properties shared across all event types.

class BaseEvent(ConfiguredBaseModel):
    type: EventType
    timestamp: Optional[int] = None
    raw_event: Optional[Any] = None

Property	Type	Description
`type`	`EventType`	The type of event (discriminator field for the union)
`timestamp`	`Optional[int]`	Timestamp when the event was created
`raw_event`	`Optional[Any]`	Original event data if this event was transformed

Lifecycle Events

These events represent the lifecycle of an agent run.

RunStartedEvent

from agentwire.core import RunStartedEvent

Signals the start of an agent run.

class RunStartedEvent(BaseEvent):
    type: Literal[EventType.RUN_STARTED]
    thread_id: str
    run_id: str

Property	Type	Description
`thread_id`	`str`	ID of the conversation thread
`run_id`	`str`	ID of the agent run

RunFinishedEvent

from agentwire.core import RunFinishedEvent

Signals the successful completion of an agent run.

class RunFinishedEvent(BaseEvent):
    type: Literal[EventType.RUN_FINISHED]
    thread_id: str
    run_id: str

Property	Type	Description
`thread_id`	`str`	ID of the conversation thread
`run_id`	`str`	ID of the agent run

RunErrorEvent

from agentwire.core import RunErrorEvent

Signals an error during an agent run.

class RunErrorEvent(BaseEvent):
    type: Literal[EventType.RUN_ERROR]
    message: str
    code: Optional[str] = None

Property	Type	Description
`message`	`str`	Error message
`code`	`Optional[str]`	Error code

StepStartedEvent

from agentwire.core import StepStartedEvent

Signals the start of a step within an agent run.

class StepStartedEvent(BaseEvent):
    type: Literal[EventType.STEP_STARTED]
    step_name: str

Property	Type	Description
`step_name`	`str`	Name of the step

StepFinishedEvent

from agentwire.core import StepFinishedEvent

Signals the completion of a step within an agent run.

class StepFinishedEvent(BaseEvent):
    type: Literal[EventType.STEP_FINISHED]
    step_name: str

Property	Type	Description
`step_name`	`str`	Name of the step

Text Message Events

These events represent the lifecycle of text messages in a conversation.

TextMessageStartEvent

from agentwire.core import TextMessageStartEvent

Signals the start of a text message.

class TextMessageStartEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_START]
    message_id: str
    role: Literal["assistant"]

Property	Type	Description
`message_id`	`str`	Unique identifier for the message
`role`	`Literal["assistant"]`	Role is always “assistant”

TextMessageContentEvent

from agentwire.core import TextMessageContentEvent

Represents a chunk of content in a streaming text message.

class TextMessageContentEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_CONTENT]
    message_id: str
    delta: str  # Non-empty string

    def model_post_init(self, __context):
        if len(self.delta) == 0:
            raise ValueError("Delta must not be an empty string")

Property	Type	Description
`message_id`	`str`	Matches the ID from TextMessageStartEvent
`delta`	`str`	Text content chunk (non-empty)

TextMessageEndEvent

from agentwire.core import TextMessageEndEvent

Signals the end of a text message.

class TextMessageEndEvent(BaseEvent):
    type: Literal[EventType.TEXT_MESSAGE_END]
    message_id: str

Property	Type	Description
`message_id`	`str`	Matches the ID from TextMessageStartEvent

Tool Call Events

These events represent the lifecycle of tool calls made by agents.

ToolCallStartEvent

from agentwire.core import ToolCallStartEvent

Signals the start of a tool call.

class ToolCallStartEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_START]
    tool_call_id: str
    tool_call_name: str
    parent_message_id: Optional[str] = None

Property	Type	Description
`tool_call_id`	`str`	Unique identifier for the tool call
`tool_call_name`	`str`	Name of the tool being called
`parent_message_id`	`Optional[str]`	ID of the parent message

ToolCallArgsEvent

from agentwire.core import ToolCallArgsEvent

Represents a chunk of argument data for a tool call.

class ToolCallArgsEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_ARGS]
    tool_call_id: str
    delta: str

Property	Type	Description
`tool_call_id`	`str`	Matches the ID from ToolCallStartEvent
`delta`	`str`	Argument data chunk

ToolCallEndEvent

from agentwire.core import ToolCallEndEvent

Signals the end of a tool call.

class ToolCallEndEvent(BaseEvent):
    type: Literal[EventType.TOOL_CALL_END]
    tool_call_id: str

Property	Type	Description
`tool_call_id`	`str`	Matches the ID from ToolCallStartEvent

State Management Events

These events are used to manage agent state.

StateSnapshotEvent

from agentwire.core import StateSnapshotEvent

Provides a complete snapshot of an agent’s state.

class StateSnapshotEvent(BaseEvent):
    type: Literal[EventType.STATE_SNAPSHOT]
    snapshot: State

Property	Type	Description
`snapshot`	`State`	Complete state snapshot

StateDeltaEvent

from agentwire.core import StateDeltaEvent

Provides a partial update to an agent’s state using JSON Patch.

class StateDeltaEvent(BaseEvent):
    type: Literal[EventType.STATE_DELTA]
    delta: List[Any]  # JSON Patch (RFC 6902)

Property	Type	Description
`delta`	`List[Any]`	Array of JSON Patch operations

MessagesSnapshotEvent

from agentwire.core import MessagesSnapshotEvent

Provides a snapshot of all messages in a conversation.

class MessagesSnapshotEvent(BaseEvent):
    type: Literal[EventType.MESSAGES_SNAPSHOT]
    messages: List[Message]

Property	Type	Description
`messages`	`List[Message]`	Array of message objects

Special Events

RawEvent

from agentwire.core import RawEvent

Used to pass through events from external systems.

class RawEvent(BaseEvent):
    type: Literal[EventType.RAW]
    event: Any
    source: Optional[str] = None

Property	Type	Description
`event`	`Any`	Original event data
`source`	`Optional[str]`	Source of the event

CustomEvent

from agentwire.core import CustomEvent

Used for application-specific custom events.

class CustomEvent(BaseEvent):
    type: Literal[EventType.CUSTOM]
    name: str
    value: Any

Property	Type	Description
`name`	`str`	Name of the custom event
`value`	`Any`	Value associated with the event

Event Discrimination

from agentwire.core import Event

The SDK uses Pydantic’s discriminated unions for event validation:

Event = Annotated[
    Union[
        TextMessageStartEvent,
        TextMessageContentEvent,
        TextMessageEndEvent,
        ToolCallStartEvent,
        ToolCallArgsEvent,
        ToolCallEndEvent,
        StateSnapshotEvent,
        StateDeltaEvent,
        MessagesSnapshotEvent,
        RawEvent,
        CustomEvent,
        RunStartedEvent,
        RunFinishedEvent,
        RunErrorEvent,
        StepStartedEvent,
        StepFinishedEvent,
    ],
    Field(discriminator="type")
]

This allows for runtime validation of events and type checking at development time.

TypeScript

Python

​Events

​EventType Enum

​BaseEvent

​Lifecycle Events

​RunStartedEvent

​RunFinishedEvent

​RunErrorEvent

​StepStartedEvent

​StepFinishedEvent

​Text Message Events

​TextMessageStartEvent

​TextMessageContentEvent

​TextMessageEndEvent

​Tool Call Events

​ToolCallStartEvent

​ToolCallArgsEvent

​ToolCallEndEvent

​State Management Events

​StateSnapshotEvent

​StateDeltaEvent

​MessagesSnapshotEvent

​Special Events

​RawEvent

​CustomEvent

​Event Discrimination