diff --git a/sdk/arch/events.mdx b/sdk/arch/events.mdx
index e53dde60..2d37f966 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 client applications
+  - 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