refactor repo by creating context/; move looping logic into conversation.py (#36)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: xingyaoww

.openhands/microagents/repo.md

@@ -146,4 +146,5 @@ This project contains my tasks of completely refactor [OpenHands](https://github
 - You can run pytest with `uv run pytest`
 - Don't write TOO MUCH test, you should write just enough to cover edge cases.
 - AFTER you edit ONE file, you should run pre-commit hook on that file via `uv run pre-commit run --files [filepath]` to make sure you didn't break it.
+- Avoid hacky trick like `sys.path.insert` when resolving package dependency
 </NOTE>

examples/hello_world.py

@@ -8,7 +8,6 @@
     Conversation,
     LLMConfig,
     Message,
-    OpenHandsConfig,
     TextContent,
     Tool,
     get_logger,
@@ -26,14 +25,11 @@
 # Configure LLM
 api_key = os.getenv("LITELLM_API_KEY")
 assert api_key is not None, "LITELLM_API_KEY environment variable is not set."
-config = OpenHandsConfig(
-    llm=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=config.llm)
+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()
@@ -54,3 +50,4 @@
         content=[TextContent(text="Hello! Can you create a new Python file named hello.py that prints 'Hello, World!'?")],
     )
 )
+conversation.run()

openhands/__init__.py

@@ -1 +1 @@
-__path__ = __import__('pkgutil').extend_path(__path__, __name__)
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

openhands/core/__init__.py

@@ -1,7 +1,7 @@
 from importlib.metadata import PackageNotFoundError, version
 
-from .agenthub import AgentBase, CodeActAgent
-from .config import LLMConfig, MCPConfig, OpenHandsConfig
+from .agent import AgentBase, CodeActAgent
+from .config import LLMConfig, MCPConfig
 from .conversation import Conversation
 from .llm import LLM, ImageContent, Message, TextContent
 from .logger import get_logger
@@ -23,7 +23,6 @@
     "CodeActAgent",
     "ActionBase",
     "ObservationBase",
-    "OpenHandsConfig",
     "LLMConfig",
     "MCPConfig",
     "get_logger",

openhands/core/agenthub/__init__.py renamed to openhands/core/agent/__init__.py

@@ -1,10 +1,8 @@
-from .agent import AgentBase
+from .base import AgentBase
 from .codeact_agent import CodeActAgent
-from .history import AgentHistory
 
 
 __all__ = [
     "CodeActAgent",
     "AgentBase",
-    "AgentHistory",
 ]

openhands/core/agent/base.py

@@ -0,0 +1,90 @@
+from abc import ABC, abstractmethod
+from types import MappingProxyType
+
+from openhands.core.context.env_context import EnvContext
+from openhands.core.conversation import ConversationCallbackType, ConversationState
+from openhands.core.llm import LLM
+from openhands.core.logger import get_logger
+from openhands.core.tool import Tool
+
+
+logger = get_logger(__name__)
+
+
+class AgentBase(ABC):
+    def __init__(
+        self,
+        llm: LLM,
+        tools: list[Tool],
+        env_context: EnvContext | None = None,
+    ) -> None:
+        """Initializes a new instance of the Agent class.
+
+        Agent should be Stateless: every step only relies on:
+        1. input ConversationState
+        2. LLM/tools/env_context that were given in __init__
+        """
+        self._llm = llm
+        self._env_context = env_context
+
+        # Load tools into an immutable dict
+        _tools_map = {}
+        for tool in tools:
+            if tool.name in _tools_map:
+                raise ValueError(f"Duplicate tool name: {tool.name}")
+            logger.debug(f"Registering tool: {tool}")
+            _tools_map[tool.name] = tool
+        self._tools = MappingProxyType(_tools_map)
+
+    @property
+    def name(self) -> str:
+        """Returns the name of the Agent."""
+        return self.__class__.__name__
+
+    @property
+    def llm(self) -> LLM:
+        """Returns the LLM instance used by the Agent."""
+        return self._llm
+
+    @property
+    def tools(self) -> MappingProxyType[str, Tool]:
+        """Returns an immutable mapping of available tools from name."""
+        return self._tools
+
+    @property
+    def env_context(self) -> EnvContext | None:
+        """Returns the environment context used by the Agent."""
+        return self._env_context
+
+    @abstractmethod
+    def init_state(
+        self,
+        state: ConversationState,
+        on_event: ConversationCallbackType | None = None,
+    ) -> ConversationState:
+        """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)
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    @abstractmethod
+    def step(
+        self,
+        state: ConversationState,
+        on_event: ConversationCallbackType | None = None,
+    ) -> ConversationState:
+        """Taking a step in the conversation.
+
+        Typically this involves:
+        1. Making a LLM call
+        2. Executing the tool
+        3. Updating the conversation state with
+            LLM calls (role="assistant") and tool results (role="tool")
+        4.1 If conversation is finished, set state.agent_finished flag
+        4.2 Otherwise, just return, Conversation will kick off the next step
+        """
+        raise NotImplementedError("Subclasses must implement this method.")

openhands/core/agenthub/codeact_agent/__init__.py renamed to openhands/core/agent/codeact_agent/__init__.py

@@ -0,0 +1,182 @@
+import json
+import os
+from typing import Callable
+
+from litellm.types.utils import (
+    ChatCompletionMessageToolCall,
+    Choices,
+    Message as LiteLLMMessage,
+    ModelResponse,
+)
+from pydantic import Field, ValidationError
+
+from openhands.core.context import EnvContext, PromptManager
+from openhands.core.conversation import ConversationCallbackType, ConversationState
+from openhands.core.llm import LLM, Message, TextContent, get_llm_metadata
+from openhands.core.logger import get_logger
+from openhands.core.tool import ActionBase, ObservationBase, Tool, ToolAnnotations
+
+from ..base import AgentBase
+
+
+logger = get_logger(__name__)
+
+"""Finish tool implementation."""
+
+
+class FinishAction(ActionBase):
+    message: str = Field(description="Final message to send to the user.")
+
+
+TOOL_DESCRIPTION = """Signals the completion of the current task or conversation.
+
+Use this tool when:
+- You have successfully completed the user's requested task
+- You cannot proceed further due to technical limitations or missing information
+
+The message should include:
+- A clear summary of actions taken and their results
+- Any next steps for the user
+- Explanation if you're unable to complete the task
+- Any follow-up questions if more information is needed
+"""
+
+
+FINISH_TOOL = Tool(
+    name="finish",
+    input_schema=FinishAction,
+    description=TOOL_DESCRIPTION,
+    annotations=ToolAnnotations(
+        title="finish",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+)
+
+
+class CodeActAgent(AgentBase):
+    def __init__(
+        self,
+        llm: LLM,
+        tools: list[Tool],
+        env_context: EnvContext | None = None,
+        system_prompt_filename: str = "system_prompt.j2",
+        cli_mode: bool = True,
+    ) -> None:
+        assert FINISH_TOOL not in tools, "Finish tool is automatically included and should not be provided."
+        super().__init__(llm=llm, tools=tools + [FINISH_TOOL], env_context=env_context)
+        self.prompt_manager = PromptManager(
+            prompt_dir=os.path.join(os.path.dirname(__file__), "prompts"),
+            system_prompt_filename=system_prompt_filename,
+        )
+        self.system_message: TextContent = self.prompt_manager.get_system_message(cli_mode=cli_mode)
+        self.max_iterations: int = 10
+
+    def init_state(
+        self,
+        state: ConversationState,
+        on_event: ConversationCallbackType | None = None,
+    ) -> ConversationState:
+        # TODO(openhands): we should add test to test this init_state will actually modify state in-place
+        messages = state.history.messages
+        if len(messages) == 0:
+            sys_msg = Message(role="system", content=[self.system_message])
+            messages.append(sys_msg)
+            if on_event:
+                on_event(sys_msg)
+            content = state.history.messages[-1].content
+            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))
+        return state
+
+    def step(
+        self,
+        state: ConversationState,
+        on_event: ConversationCallbackType | None = None,
+    ) -> ConversationState:
+        # Get LLM Response (Action)
+        _messages = self.llm.format_messages_for_llm(state.history.messages)
+        logger.debug(f"Sending messages to LLM: {json.dumps(_messages, indent=2)}")
+        response: ModelResponse = self.llm.completion(
+            messages=_messages,
+            tools=[tool.to_openai_tool() for tool in self.tools.values()],
+            extra_body={"metadata": get_llm_metadata(model_name=self.llm.config.model, agent_name=self.name)},
+        )
+        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
+            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:
+                state = self._handle_tool_call(tool_call, state, on_event)
+        else:
+            logger.info("LLM produced a message response - awaits user input")
+            state.agent_finished = True
+        return state
+
+    def _handle_tool_call(
+        self,
+        tool_call: ChatCompletionMessageToolCall,
+        state: ConversationState,
+        on_event: Callable[[Message | ActionBase | ObservationBase], None] | None = None,
+    ) -> ConversationState:
+        assert tool_call.type == "function"
+        tool_name = tool_call.function.name
+        assert tool_name is not None, "Tool call must have a name"
+        tool = self.tools.get(tool_name, None)
+        # Handle non-existing tools
+        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)]))
+            state.agent_finished = True
+            return state
+
+        # 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)]))
+            return state
+
+        # Early return for finish action (no need for tool execution)
+        if isinstance(action, FinishAction):
+            assert tool.name == FINISH_TOOL.name, "FinishAction must be used with the finish tool"
+            state.agent_finished = True
+            return state
+
+        # 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)
+        return state