From d3da582028c6f82e81b6fcc15a73ac7af4ab4ca7 Mon Sep 17 00:00:00 2001 From: enyst Date: Sat, 8 Nov 2025 00:35:23 +0000 Subject: [PATCH 1/2] sdk/docs: document AgentErrorEvent vs ConversationErrorEvent in Events architecture page Co-authored-by: openhands --- sdk/arch/events.mdx | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/sdk/arch/events.mdx b/sdk/arch/events.mdx index e53dde60..d948b2ac 100644 --- a/sdk/arch/events.mdx +++ b/sdk/arch/events.mdx @@ -179,6 +179,26 @@ flowchart LR - **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 UI + - Code: https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/event/conversation_error.py + ## See Also - **[Agent Architecture](/sdk/arch/agent)** - How agents read and write events From caf662731deeb0c8d10facefb96894700d3ce085 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Sat, 8 Nov 2025 02:50:02 +0100 Subject: [PATCH 2/2] Update sdk/arch/events.mdx --- sdk/arch/events.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/arch/events.mdx b/sdk/arch/events.mdx index d948b2ac..2d37f966 100644 --- a/sdk/arch/events.mdx +++ b/sdk/arch/events.mdx @@ -196,7 +196,7 @@ Two distinct error events exist in the SDK, with different purpose and visibilit - 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 UI + - 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