Add ask_agent method to conversation classes for simple LLM completions (#1227)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: simonrosenberg <157206163+simonrosenberg@users.noreply.github.com>
Co-authored-by: Xingyao Wang <xingyao@all-hands.dev>

Author: 4 people

.github/workflows/check-documented-examples.yml

@@ -25,12 +25,24 @@ jobs:
               with:
                   fetch-depth: 0
 
-            - name: Checkout docs repository
+            - name: Checkout docs repository (try feature branch)
               uses: actions/checkout@v5
+              continue-on-error: true
+              id: checkout-feature
               with:
                   repository: OpenHands/docs
                   path: docs
                   fetch-depth: 0
+                  ref: ${{ github.head_ref || github.ref_name }}
+
+            - name: Checkout docs repository (fallback to main)
+              if: steps.checkout-feature.outcome == 'failure'
+              uses: actions/checkout@v5
+              with:
+                  repository: OpenHands/docs
+                  path: docs
+                  fetch-depth: 0
+                  ref: main
 
             - name: Set up Python
               uses: actions/setup-python@v6

examples/01_standalone_sdk/28_ask_agent_example.py

@@ -0,0 +1,143 @@
+"""
+Example demonstrating the ask_agent functionality for getting sidebar replies
+from the agent for a running conversation.
+
+This example shows how to use ask_agent() to get quick responses from the agent
+about the current conversation state without interrupting the main execution flow.
+"""
+
+import os
+import threading
+import time
+from datetime import datetime
+
+from pydantic import SecretStr
+
+from openhands.sdk import (
+    LLM,
+    Agent,
+    Conversation,
+)
+from openhands.sdk.conversation import ConversationVisualizerBase
+from openhands.sdk.event import Event
+from openhands.sdk.tool import Tool
+from openhands.tools.file_editor import FileEditorTool
+from openhands.tools.task_tracker import TaskTrackerTool
+from openhands.tools.terminal import TerminalTool
+
+
+# Configure LLM
+api_key = os.getenv("LLM_API_KEY")
+assert api_key is not None, "LLM_API_KEY environment variable is not set."
+model = os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929")
+base_url = os.getenv("LLM_BASE_URL")
+llm = LLM(
+    usage_id="agent",
+    model=model,
+    base_url=base_url,
+    api_key=SecretStr(api_key),
+)
+
+# Tools
+cwd = os.getcwd()
+tools = [
+    Tool(name=TerminalTool.name),
+    Tool(name=FileEditorTool.name),
+    Tool(name=TaskTrackerTool.name),
+]
+
+
+class MinimalVisualizer(ConversationVisualizerBase):
+    """A minimal visualizer that print the raw events as they occur."""
+
+    count = 0
+
+    def on_event(self, event: Event) -> None:
+        """Handle events for minimal progress visualization."""
+        print(f"\n\n[EVENT {self.count}] {type(event).__name__}")
+        self.count += 1
+
+
+# Agent
+agent = Agent(llm=llm, tools=tools)
+conversation = Conversation(
+    agent=agent, workspace=cwd, visualizer=MinimalVisualizer, max_iteration_per_run=5
+)
+
+
+def timestamp() -> str:
+    return datetime.now().strftime("%H:%M:%S")
+
+
+print("=== Ask Agent Example ===")
+print("This example demonstrates asking questions during conversation execution")
+
+# Step 1: Build conversation context
+print(f"\n[{timestamp()}] Building conversation context...")
+conversation.send_message("Explore the current directory and describe the architecture")
+
+# Step 2: Start conversation in background thread
+print(f"[{timestamp()}] Starting conversation in background thread...")
+thread = threading.Thread(target=conversation.run)
+thread.start()
+
+# Give the agent time to start processing
+time.sleep(2)
+
+# Step 3: Use ask_agent while conversation is running
+print(f"\n[{timestamp()}] Using ask_agent while conversation is processing...")
+
+# Ask context-aware questions
+questions_and_responses = []
+
+question_1 = "Summarize the activity so far in 1 sentence."
+print(f"\n[{timestamp()}] Asking: {question_1}")
+response1 = conversation.ask_agent(question_1)
+questions_and_responses.append((question_1, response1))
+print(f"Response: {response1}")
+
+time.sleep(1)
+
+question_2 = "How's the progress?"
+print(f"\n[{timestamp()}] Asking: {question_2}")
+response2 = conversation.ask_agent(question_2)
+questions_and_responses.append((question_2, response2))
+print(f"Response: {response2}")
+
+time.sleep(1)
+
+question_3 = "Have you finished running?"
+print(f"\n[{timestamp()}] {question_3}")
+response3 = conversation.ask_agent(question_3)
+questions_and_responses.append((question_3, response3))
+print(f"Response: {response3}")
+
+# Step 4: Wait for conversation to complete
+print(f"\n[{timestamp()}] Waiting for conversation to complete...")
+thread.join()
+
+# Step 5: Verify conversation state wasn't affected
+final_event_count = len(conversation.state.events)
+# Step 6: Ask a final question after conversation completion
+print(f"\n[{timestamp()}] Asking final question after completion...")
+final_response = conversation.ask_agent(
+    "Can you summarize what you accomplished in this conversation?"
+)
+print(f"Final response: {final_response}")
+
+# Step 7: Summary
+print("\n" + "=" * 60)
+print("SUMMARY OF ASK_AGENT DEMONSTRATION")
+print("=" * 60)
+
+print("\nQuestions and Responses:")
+for i, (question, response) in enumerate(questions_and_responses, 1):
+    print(f"\n{i}. Q: {question}")
+    print(f"   A: {response[:100]}{'...' if len(response) > 100 else ''}")
+
+final_truncated = final_response[:100] + ("..." if len(final_response) > 100 else "")
+print(f"\nFinal Question Response: {final_truncated}")
+
+# Report cost
+cost = llm.metrics.accumulated_cost
+print(f"EXAMPLE_COST: {cost:.4f}")

openhands-agent-server/openhands/agent_server/conversation_router.py

@@ -9,6 +9,8 @@
 from openhands.agent_server.conversation_service import ConversationService
 from openhands.agent_server.dependencies import get_conversation_service
 from openhands.agent_server.models import (
+    AskAgentRequest,
+    AskAgentResponse,
     ConversationInfo,
     ConversationPage,
     ConversationSortOrder,
@@ -289,3 +291,19 @@ async def generate_conversation_title(
     if title is None:
         raise HTTPException(status.HTTP_500_INTERNAL_SERVER_ERROR)
     return GenerateTitleResponse(title=title)
+
+
+@conversation_router.post(
+    "/{conversation_id}/ask_agent",
+    responses={404: {"description": "Item not found"}},
+)
+async def ask_agent(
+    conversation_id: UUID,
+    request: AskAgentRequest,
+    conversation_service: ConversationService = Depends(get_conversation_service),
+) -> AskAgentResponse:
+    """Ask the agent a simple question without affecting conversation state."""
+    response = await conversation_service.ask_agent(conversation_id, request.question)
+    if response is None:
+        raise HTTPException(status.HTTP_500_INTERNAL_SERVER_ERROR)
+    return AskAgentResponse(response=response)

openhands-agent-server/openhands/agent_server/conversation_service.py

@@ -320,6 +320,18 @@ async def generate_conversation_title(
         title = await event_service.generate_title(llm=llm, max_length=max_length)
         return title
 
+    async def ask_agent(self, conversation_id: UUID, question: str) -> str | None:
+        """Ask the agent a simple question without affecting conversation state."""
+        if self._event_services is None:
+            raise ValueError("inactive_service")
+        event_service = self._event_services.get(conversation_id)
+        if event_service is None:
+            return None
+
+        # Delegate to EventService to avoid accessing private conversation internals
+        response = await event_service.ask_agent(question)
+        return response
+
     async def __aenter__(self):
         self.conversations_dir.mkdir(parents=True, exist_ok=True)
         self._event_services = {}

openhands-agent-server/openhands/agent_server/event_service.py

@@ -463,6 +463,17 @@ async def generate_title(
             None, self._conversation.generate_title, resolved_llm, max_length
         )
 
+    async def ask_agent(self, question: str) -> str:
+        """Ask the agent a simple question without affecting conversation state.
+
+        Delegates to LocalConversation in an executor to avoid blocking the event loop.
+        """
+        if not self._conversation:
+            raise ValueError("inactive_service")
+
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._conversation.ask_agent, question)
+
     async def get_state(self) -> ConversationState:
         if not self._conversation:
             raise ValueError("inactive_service")

openhands-agent-server/openhands/agent_server/models.py

@@ -199,6 +199,18 @@ class GenerateTitleResponse(BaseModel):
     title: str = Field(description="The generated title for the conversation")
 
 
+class AskAgentRequest(BaseModel):
+    """Payload to ask the agent a simple question."""
+
+    question: str = Field(description="The question to ask the agent")
+
+
+class AskAgentResponse(BaseModel):
+    """Response containing the agent's answer."""
+
+    response: str = Field(description="The agent's response to the question")
+
+
 class BashEventBase(DiscriminatedUnionMixin, ABC):
     """Base class for all bash event types"""
 

openhands-sdk/openhands/sdk/agent/agent.py

@@ -5,8 +5,11 @@
 import openhands.sdk.security.analyzer as analyzer
 import openhands.sdk.security.risk as risk
 from openhands.sdk.agent.base import AgentBase
-from openhands.sdk.agent.utils import fix_malformed_tool_arguments
-from openhands.sdk.context.view import View
+from openhands.sdk.agent.utils import (
+    fix_malformed_tool_arguments,
+    make_llm_completion,
+    prepare_llm_messages,
+)
 from openhands.sdk.conversation import (
     ConversationCallbackType,
     ConversationState,
@@ -145,49 +148,27 @@ def step(
             self._execute_actions(conversation, pending_actions, on_event)
             return
 
-        # If a condenser is registered with the agent, we need to give it an
-        # opportunity to transform the events. This will either produce a list
-        # of events, exactly as expected, or a new condensation that needs to be
-        # processed before the agent can sample another action.
-        if self.condenser is not None:
-            view = View.from_events(state.events)
-            condensation_result = self.condenser.condense(view)
+        # Prepare LLM messages using the utility function
+        _messages_or_condensation = prepare_llm_messages(
+            state.events, condenser=self.condenser
+        )
 
-            match condensation_result:
-                case View():
-                    llm_convertible_events = condensation_result.events
+        # Process condensation event before agent sampels another action
+        if isinstance(_messages_or_condensation, Condensation):
+            on_event(_messages_or_condensation)
+            return
 
-                case Condensation():
-                    on_event(condensation_result)
-                    return None
+        _messages = _messages_or_condensation
 
-        else:
-            llm_convertible_events = [
-                e for e in state.events if isinstance(e, LLMConvertibleEvent)
-            ]
-
-        # Get LLM Response (Action)
-        _messages = LLMConvertibleEvent.events_to_messages(llm_convertible_events)
         logger.debug(
             "Sending messages to LLM: "
             f"{json.dumps([m.model_dump() for m in _messages[1:]], indent=2)}"
         )
 
         try:
-            if self.llm.uses_responses_api():
-                llm_response = self.llm.responses(
-                    messages=_messages,
-                    tools=list(self.tools_map.values()),
-                    include=None,
-                    store=False,
-                    add_security_risk_prediction=True,
-                )
-            else:
-                llm_response = self.llm.completion(
-                    messages=_messages,
-                    tools=list(self.tools_map.values()),
-                    add_security_risk_prediction=True,
-                )
+            llm_response = make_llm_completion(
+                self.llm, _messages, tools=list(self.tools_map.values())
+            )
         except FunctionCallValidationError as e:
             logger.warning(f"LLM generated malformed function call: {e}")
             error_message = MessageEvent(

openhands-sdk/openhands/sdk/agent/base.py

@@ -26,6 +26,7 @@
     from openhands.sdk.conversation import ConversationState, LocalConversation
     from openhands.sdk.conversation.types import ConversationCallbackType
 
+
 logger = get_logger(__name__)