refactor the system to use Event Types (#44)

Co-authored-by: openhands <[email protected]>

Author: xingyaoww

examples/hello_world.py

@@ -4,13 +4,12 @@
 
 from openhands.core import (
     LLM,
-    ActionBase,
     CodeActAgent,
     Conversation,
-    ConversationEventType,
+    EventType,
     LLMConfig,
+    LLMConvertibleEvent,
     Message,
-    ObservationBase,
     TextContent,
     Tool,
     get_logger,
@@ -28,11 +27,13 @@
 # Configure LLM
 api_key = os.getenv("LITELLM_API_KEY")
 assert api_key is not None, "LITELLM_API_KEY environment variable is not set."
-llm = LLM(config=LLMConfig(
-    model="litellm_proxy/anthropic/claude-sonnet-4-20250514",
-    base_url="https://llm-proxy.eval.all-hands.dev",
-    api_key=SecretStr(api_key),
-))
+llm = LLM(
+    config=LLMConfig(
+        model="litellm_proxy/anthropic/claude-sonnet-4-20250514",
+        base_url="https://llm-proxy.eval.all-hands.dev",
+        api_key=SecretStr(api_key),
+    )
+)
 
 # Tools
 cwd = os.getcwd()
@@ -47,15 +48,13 @@
 agent = CodeActAgent(llm=llm, tools=tools)
 
 llm_messages = []  # collect raw LLM messages
-def conversation_callback(event: ConversationEventType):
-    # print all the actions
-    if isinstance(event, ActionBase):
-        logger.info(f"Found a conversation action: {event}")
-    elif isinstance(event, ObservationBase):
-        logger.info(f"Found a conversation observation: {event}")
-    elif isinstance(event, Message):
-        logger.info(f"Found a conversation message: {str(event)[:200]}...")
-        llm_messages.append(event.model_dump())
+
+
+def conversation_callback(event: EventType):
+    logger.info(f"Found a conversation message: {str(event)[:200]}...")
+    if isinstance(event, LLMConvertibleEvent):
+        llm_messages.append(event.to_llm_message())
+
 
 conversation = Conversation(agent=agent, callbacks=[conversation_callback])
 
@@ -67,7 +66,7 @@ def conversation_callback(event: ConversationEventType):
 )
 conversation.run()
 
-print("="*100)
+print("=" * 100)
 print("Conversation finished. Got the following LLM messages:")
 for i, message in enumerate(llm_messages):
     print(f"Message {i}: {str(message)[:200]}")

openhands/core/__init__.py

@@ -2,7 +2,8 @@
 
 from .agent import AgentBase, CodeActAgent
 from .config import LLMConfig, MCPConfig
-from .conversation import Conversation, ConversationCallbackType, ConversationEventType
+from .conversation import Conversation, ConversationCallbackType
+from .event import EventBase, EventType, LLMConvertibleEvent
 from .llm import LLM, ImageContent, Message, TextContent
 from .logger import get_logger
 from .tool import ActionBase, ObservationBase, Tool
@@ -28,6 +29,8 @@
     "get_logger",
     "Conversation",
     "ConversationCallbackType",
-    "ConversationEventType",
+    "EventType",
+    "EventBase",
+    "LLMConvertibleEvent",
     "__version__",
 ]

openhands/core/agent/base.py

@@ -3,7 +3,7 @@
 
 from openhands.core.context.env_context import EnvContext
 from openhands.core.conversation import ConversationCallbackType, ConversationState
-from openhands.core.llm import LLM, Message
+from openhands.core.llm import LLM
 from openhands.core.logger import get_logger
 from openhands.core.tool import Tool
 
@@ -60,15 +60,11 @@ def env_context(self) -> EnvContext | None:
     def init_state(
         self,
         state: ConversationState,
-        initial_user_message: Message | None = None,
-        on_event: ConversationCallbackType | None = None,
+        on_event: ConversationCallbackType,
     ) -> None:
         """Initialize the empty conversation state to prepare the agent for user messages.
 
-        Typically this involves:
-        1. Adding system message
-        2. Adding initial user messages with environment context
-            (e.g., microagents, current working dir, etc)
+        Typically this involves adding system message
 
         NOTE: state will be mutated in-place.
         """
@@ -78,7 +74,7 @@ def init_state(
     def step(
         self,
         state: ConversationState,
-        on_event: ConversationCallbackType | None = None,
+        on_event: ConversationCallbackType,
     ) -> None:
         """Taking a step in the conversation.
 

openhands/core/agent/codeact_agent/codeact_agent.py

@@ -1,6 +1,6 @@
 import json
 import os
-from typing import Callable
+from typing import cast
 
 from litellm.types.utils import (
     ChatCompletionMessageToolCall,
@@ -12,6 +12,7 @@
 
 from openhands.core.context import EnvContext, PromptManager
 from openhands.core.conversation import ConversationCallbackType, ConversationState
+from openhands.core.event import ActionEvent, AgentErrorEvent, LLMConvertibleEvent, MessageEvent, ObservationEvent, SystemPromptEvent
 from openhands.core.llm import LLM, Message, TextContent, get_llm_metadata
 from openhands.core.logger import get_logger
 from openhands.core.tool import BUILT_IN_TOOLS, ActionBase, FinishTool, ObservationBase, Tool
@@ -22,7 +23,6 @@
 logger = get_logger(__name__)
 
 
-
 class CodeActAgent(AgentBase):
     def __init__(
         self,
@@ -45,43 +45,25 @@ def __init__(
     def init_state(
         self,
         state: ConversationState,
-        initial_user_message: Message | None = None,
-        on_event: ConversationCallbackType | None = None,
+        on_event: ConversationCallbackType,
     ) -> None:
         # TODO(openhands): we should add test to test this init_state will actually modify state in-place
-        messages = state.history.messages
+        messages = [e.to_llm_message() for e in state.events]
         if len(messages) == 0:
             # Prepare system message
-            sys_msg = Message(role="system", content=[self.system_message])
-            messages.append(sys_msg)
-            if on_event:
-                on_event(sys_msg)
-            if initial_user_message is None:
-                raise ValueError("initial_user_message must be provided in init_state for CodeActAgent")
-            
-            # Prepare user message
-            content = initial_user_message.content
-            # TODO: think about this - we might want to handle this outside Agent but inside Conversation (e.g., in send_messages)
-            # downside of handling them inside Conversation would be: conversation don't have access
-            # to *any* action execution runtime information
-            if self.env_context:
-                initial_env_context: list[TextContent] = self.env_context.render(self.prompt_manager)
-                content += initial_env_context
-            user_msg = Message(role="user", content=content)
-            messages.append(user_msg)
-            if on_event:
-                on_event(user_msg)
-            if self.env_context and self.env_context.activated_microagents:
-                for microagent in self.env_context.activated_microagents:
-                    state.history.microagent_activations.append((microagent.name, len(messages) - 1))
+            event = SystemPromptEvent(source="agent", system_prompt=self.system_message, tools=[t.to_openai_tool() for t in self.tools.values()])
+            # TODO: maybe we should combine this into on_event?
+            state.events.append(event)
+            on_event(event)
 
     def step(
         self,
         state: ConversationState,
-        on_event: ConversationCallbackType | None = None,
+        on_event: ConversationCallbackType,
     ) -> None:
         # Get LLM Response (Action)
-        _messages = self.llm.format_messages_for_llm(state.history.messages)
+        llm_convertible_events = cast(list[LLMConvertibleEvent], [e for e in state.events if isinstance(e, LLMConvertibleEvent)])
+        _messages = self.llm.format_messages_for_llm(LLMConvertibleEvent.events_to_messages(llm_convertible_events))
         logger.debug(f"Sending messages to LLM: {json.dumps(_messages, indent=2)}")
         response: ModelResponse = self.llm.completion(
             messages=_messages,
@@ -90,30 +72,54 @@ def step(
         )
         assert len(response.choices) == 1 and isinstance(response.choices[0], Choices)
         llm_message: LiteLLMMessage = response.choices[0].message  # type: ignore
-
         message = Message.from_litellm_message(llm_message)
-        state.history.messages.append(message)
-        if on_event:
-            on_event(message)
 
         if message.tool_calls and len(message.tool_calls) > 0:
             tool_call: ChatCompletionMessageToolCall
+            if any(tc.type != "function" for tc in message.tool_calls):
+                logger.warning("LLM returned tool calls but some are not of type 'function' - ignoring those")
+
             tool_calls = [tool_call for tool_call in message.tool_calls if tool_call.type == "function"]
             assert len(tool_calls) > 0, "LLM returned tool calls but none are of type 'function'"
-            for tool_call in tool_calls:
-                self._handle_tool_call(tool_call, state, on_event)
+            if not all(isinstance(c, TextContent) for c in message.content):
+                logger.warning("LLM returned tool calls but message content is not all TextContent - ignoring non-text content")
+
+            # Generate unique batch ID for this LLM response
+            thought_content = [c for c in message.content if isinstance(c, TextContent)]
+
+            action_events = []
+            for i, tool_call in enumerate(tool_calls):
+                action_event = self._get_action_events(
+                    state,
+                    tool_call,
+                    llm_response_id=response.id,
+                    on_event=on_event,
+                    thought=thought_content if i == 0 else [],  # Only first gets thought
+                )
+                if action_event is None:
+                    continue
+                action_events.append(action_event)
+                state.events.append(action_event)
+
+            for action_event in action_events:
+                self._execute_action_events(state, action_event, on_event=on_event)
         else:
             logger.info("LLM produced a message response - awaits user input")
             state.agent_finished = True
+            msg_event = MessageEvent(source="agent", llm_message=message)
+            state.events.append(msg_event)
+            on_event(msg_event)
 
-    def _handle_tool_call(
+    def _get_action_events(
         self,
-        tool_call: ChatCompletionMessageToolCall,
         state: ConversationState,
-        on_event: Callable[[Message | ActionBase | ObservationBase], None] | None = None,
-    ) -> None:
+        tool_call: ChatCompletionMessageToolCall,
+        llm_response_id: str,
+        on_event: ConversationCallbackType,
+        thought: list[TextContent] = [],
+    ) -> ActionEvent | None:
         """Handle tool calls from the LLM.
-        
+
         NOTE: state will be mutated in-place.
         """
         assert tool_call.type == "function"
@@ -124,35 +130,47 @@ def _handle_tool_call(
         if tool is None:
             err = f"Tool '{tool_name}' not found. Available: {list(self.tools.keys())}"
             logger.error(err)
-            state.history.messages.append(Message(role="user", content=[TextContent(text=err)]))
+            event = AgentErrorEvent(error=err)
+            state.events.append(event)
+            on_event(event)
             state.agent_finished = True
             return
 
         # Validate arguments
         try:
             action: ActionBase = tool.action_type.model_validate(json.loads(tool_call.function.arguments))
-            if on_event:
-                on_event(action)
         except (json.JSONDecodeError, ValidationError) as e:
             err = f"Error validating args {tool_call.function.arguments} for tool '{tool.name}': {e}"
-            logger.error(err)
-            state.history.messages.append(Message(role="tool", name=tool.name, tool_call_id=tool_call.id, content=[TextContent(text=err)]))
+            event = AgentErrorEvent(error=err)
+            state.events.append(event)
+            on_event(event)
             return
 
+        # Create one ActionEvent per action
+        action_event = ActionEvent(action=action, thought=thought, tool_name=tool.name, tool_call_id=tool_call.id, tool_call=tool_call, llm_response_id=llm_response_id)
+        on_event(action_event)
+        return action_event
+
+    def _execute_action_events(self, state: ConversationState, action_event: ActionEvent, on_event: ConversationCallbackType):
+        """Execute action events and update the conversation state.
+
+        It will call the tool's executor and update the state & call callback fn with the observation.
+        """
+        tool = self.tools.get(action_event.tool_name, None)
+        if tool is None:
+            raise RuntimeError(f"Tool '{action_event.tool_name}' not found. This should not happen as it was checked earlier.")
+
         # Execute actions!
         if tool.executor is None:
             raise RuntimeError(f"Tool '{tool.name}' has no executor")
-        observation: ObservationBase = tool.executor(action)
-        tool_msg = Message(
-            role="tool",
-            name=tool.name,
-            tool_call_id=tool_call.id,
-            content=[TextContent(text=observation.agent_observation)],
-        )
-        state.history.messages.append(tool_msg)
-        if on_event:
-            on_event(observation)
+        observation: ObservationBase = tool.executor(action_event.action)
+        assert isinstance(observation, ObservationBase), f"Tool '{tool.name}' executor must return an ObservationBase"
+
+        obs_event = ObservationEvent(observation=observation, action_id=action_event.id, tool_name=tool.name, tool_call_id=action_event.tool_call.id)
+        on_event(obs_event)
 
         # Set conversation state
         if tool.name == FinishTool.name:
             state.agent_finished = True
+        state.events.append(obs_event)
+        return obs_event

openhands/core/context/__init__.py

@@ -4,7 +4,6 @@
     RepositoryInfo,
     RuntimeInfo,
 )
-from .history import AgentHistory
 from .message_context import MessageContext
 from .microagents import (
     BaseMicroagent,
@@ -32,5 +31,4 @@
     "MicroagentType",
     "MicroagentKnowledge",
     "load_microagents_from_dir",
-    "AgentHistory",
 ]

openhands/core/context/history.py

@@ -1,8 +1,5 @@
-
 class LLMContextManager:
-    """Context manager for messages we send to LLM.
-    
-    
-    """
+    """Context manager for messages we send to LLM."""
+
     def __init__(self) -> None:
         pass

openhands/core/context/manager.py

@@ -1,7 +1,7 @@
 from .conversation import Conversation
 from .state import ConversationState
-from .types import ConversationCallbackType, ConversationEventType
+from .types import ConversationCallbackType
 from .visualizer import ConversationVisualizer
 
 
-__all__ = ["Conversation", "ConversationState", "ConversationCallbackType", "ConversationEventType", "ConversationVisualizer"]
+__all__ = ["Conversation", "ConversationState", "ConversationCallbackType", "ConversationVisualizer"]