Events

High-level architecture of the typed event framework

The Event System provides an immutable, type-safe event framework that drives agent execution and state management. Events form an append-only log that serves as both the agent’s memory and the integration point for auxiliary services.

Source: openhands-sdk/openhands/sdk/event/

Core Responsibilities

The Event System has four primary responsibilities:

1. Type Safety - Enforce event schemas through Pydantic models
2. LLM Integration - Convert events to/from LLM message formats
3. Append-Only Log - Maintain immutable event history
4. Service Integration - Enable observers to react to event streams

Architecture

Key Components

Component	Purpose	Design
Event	Base event class	Immutable Pydantic model with ID, timestamp, source
LLMConvertibleEvent	LLM-compatible events	Abstract class with to_llm_message() method
MessageEvent	Text messages	User or assistant conversational messages with skills
ActionEvent	Tool calls	Agent tool invocations with thought, reasoning, security risk
ObservationBaseEvent	Tool response base	Base for all tool call responses
ObservationEvent	Tool results	Successful tool execution outcomes
UserRejectObservation	User rejection	User rejected action in confirmation mode
AgentErrorEvent	Agent errors	Errors from agent/scaffold (not model output)
SystemPromptEvent	System context	System prompt with tool schemas
CondensationSummaryEvent	Condenser summary	LLM-convertible summary of forgotten events
ConversationStateUpdateEvent	State updates	Key-value conversation state changes
Condensation	Condensation result	Events being forgotten with optional summary
CondensationRequest	Request compression	Trigger for conversation history compression
PauseEvent	User pause	User requested pause of agent execution

Event Types

LLM-Convertible Events

Events that participate in agent reasoning and can be converted to LLM messages:

Event Type	Source	Content	LLM Role
MessageEvent (user)	user	Text, images	user
MessageEvent (agent)	agent	Text reasoning, skills	assistant
ActionEvent	agent	Tool call with thought, reasoning, security risk	assistant with tool_calls
ObservationEvent	environment	Tool execution result	tool
UserRejectObservation	environment	Rejection reason	tool
AgentErrorEvent	agent	Error details	tool
SystemPromptEvent	agent	System prompt with tool schemas	system
CondensationSummaryEvent	environment	Summary of forgotten events	user

The event system bridges agent events to LLM messages:

Special Handling - Parallel Function Calling:

When multiple ActionEvents share the same llm_response_id (parallel function calling):

1. Group all ActionEvents by llm_response_id
2. Combine into single Message with multiple tool_calls
3. Only first event’s thought, reasoning_content, and thinking_blocks are included
4. All subsequent events in the batch have empty thought fields

Example:

ActionEvent(llm_response_id="abc123", thought="Let me check...", tool_call=tool1)
ActionEvent(llm_response_id="abc123", thought=[], tool_call=tool2)
→ Combined into single Message(role="assistant", content="Let me check...", tool_calls=[tool1, tool2])

Internal Events

Events for metadata, control flow, and user actions (not sent to LLM):

Event Type	Source	Purpose	Key Fields
ConversationStateUpdateEvent	environment	State synchronization	key (field name), value (serialized data)
CondensationRequest	environment	Trigger history compression	Signal to condenser when context window exceeded
Condensation	environment	Compression result	forgotten_event_ids, summary, summary_offset
PauseEvent	user	User pause action	Indicates agent execution was paused by user

Source Types:

• user: Event originated from user input
• agent: Event generated by agent logic
• environment: Event from system/framework/tools

Component Relationships

How Events Integrate

source vs LLM role

Events often carry two different concepts that are easy to confuse:

• Event.source: where the event originated (user, agent, or environment). This is about attribution.
• LLM role (e.g. Message.role / MessageEvent.llm_message.role): how the event should be represented to the LLM (system, user, assistant, tool). This is about LLM formatting.

These fields are intentionally independent.

Common examples include:

• Observations: tool results are typically source="environment" and represented to the LLM with role="tool".
• Synthetic framework messages: the SDK may inject feedback or control messages (e.g. from hooks) as source="environment" while still using an LLM role="user" so the agent reads it as a user-facing instruction.

Do not infer event origin from LLM role. If you need to distinguish real user input from synthetic/framework messages, rely on Event.source (and any explicit metadata fields on the event), not the LLM role.

Relationship Characteristics:

• Agent → Events: Reads history for context, writes actions/messages
• Conversation → Events: Owns and persists event log
• Tools → Events: Create ObservationEvents after execution
• Services → Events: Read-only observers for monitoring, visualization

Error Events: Agent vs Conversation

Two distinct error events exist in the SDK, with different purpose and visibility:

• AgentErrorEvent

  • Type: ObservationBaseEvent (LLM-convertible)
  • Scope: Error for a specific tool call (has tool_name and tool_call_id)
  • Source: “agent”
  • LLM visibility: Sent as a tool message so the model can react/recover
  • Effect: Conversation continues; not a terminal state
  • Code: https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/llm_convertible/observation.py

• ConversationErrorEvent

  • Type: Event (not LLM-convertible)
  • Scope: Conversation-level runtime failure (no tool_name/tool_call_id)
  • Source: typically “environment”
  • LLM visibility: Not sent to the model
  • Effect: Run loop transitions to ERROR and run() raises ConversationRunError; surface top-level error to client applications
  • Code: https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_error.py

See Also

• Agent Architecture - How agents read and write events
• Conversation Architecture - Event log management
• Tool System - ActionEvent and ObservationEvent generation
• Condenser - Event history compression