feat: Expose agent final response via REST API endpoint (#2690)

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: Engel Nyst <engel.nyst@gmail.com>

Author: 3 people

openhands-agent-server/AGENTS.md

@@ -14,6 +14,16 @@ This package lives in the monorepo root. Typical commands (run from repo root):
 When adding non-Python files (JS, templates, etc.) loaded at runtime, add them to `openhands-agent-server/openhands/agent_server/agent-server.spec` using `collect_data_files`.
 
 
+## Live server integration tests
+
+Small endpoint additions or changes to server behaviour should be covered by a
+test in `tests/cross/test_remote_conversation_live_server.py`.  These tests spin
+up a real FastAPI server with a patched LLM and exercise the full HTTP / WebSocket
+stack end-to-end.  Add or extend a test there whenever the change is localised
+enough that a single new test function (or a few assertions added to an existing
+test) captures the expected behaviour.
+
+
 ## Concurrency / async safety
 
 - `ConversationState` uses a synchronous `FIFOLock`. In async agent-server code, never do `with conversation._state` directly on the event loop when the conversation may be running.

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

@@ -12,6 +12,7 @@
 )
 from openhands.agent_server.dependencies import get_conversation_service
 from openhands.agent_server.models import (
+    AgentResponseResult,
     AskAgentRequest,
     AskAgentResponse,
     ConversationInfo,
@@ -113,6 +114,27 @@ async def get_conversation(
     return conversation
 
 
+@conversation_router.get(
+    "/{conversation_id}/agent_final_response",
+    responses={404: {"description": "Conversation not found"}},
+)
+async def get_conversation_agent_final_response(
+    conversation_id: UUID,
+    conversation_service: ConversationService = Depends(get_conversation_service),
+) -> AgentResponseResult:
+    """Get the agent's final response for a conversation.
+
+    Returns the text of the last agent finish message (FinishAction) or
+    the last agent text response (MessageEvent). Returns an empty string
+    if the agent has not produced a final response yet.
+    """
+    event_service = await conversation_service.get_event_service(conversation_id)
+    if event_service is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND)
+    response = await event_service.get_agent_final_response()
+    return AgentResponseResult(response=response)
+
+
 @conversation_router.get("")
 async def batch_get_conversations(
     ids: Annotated[list[UUID], Query()],

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

@@ -13,6 +13,7 @@
 from openhands.agent_server.pub_sub import PubSub, Subscriber
 from openhands.sdk import LLM, AgentBase, Event, Message, get_logger
 from openhands.sdk.conversation.impl.local_conversation import LocalConversation
+from openhands.sdk.conversation.response_utils import get_agent_final_response
 from openhands.sdk.conversation.secret_registry import SecretValue
 from openhands.sdk.conversation.state import (
     ConversationExecutionStatus,
@@ -705,6 +706,28 @@ async def condense(self) -> None:
         loop = asyncio.get_running_loop()
         return await loop.run_in_executor(None, self._conversation.condense)
 
+    def _get_agent_final_response_sync(self) -> str:
+        """Extract the agent's final response from the conversation events.
+
+        Reads directly from the EventLog without acquiring the state lock.
+        EventLog reads are safe without the FIFOLock because events are
+        append-only and immutable once written.
+        """
+        if not self._conversation:
+            raise ValueError("inactive_service")
+        return get_agent_final_response(self._conversation._state.events)
+
+    async def get_agent_final_response(self) -> str:
+        """Extract the agent's final response from the conversation events.
+
+        Returns the text from the last FinishAction or agent MessageEvent,
+        or empty string if no final response is found.
+        """
+        if not self._conversation:
+            raise ValueError("inactive_service")
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._get_agent_final_response_sync)
+
     async def get_state(self) -> ConversationState:
         if not self._conversation:
             raise ValueError("inactive_service")

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

@@ -459,6 +459,22 @@ class AskAgentResponse(BaseModel):
     response: str = Field(description="The agent's response to the question")
 
 
+class AgentResponseResult(BaseModel):
+    """The agent's final response for a conversation.
+
+    Contains the text of the last agent finish message or text response.
+    Empty string if the agent has not produced a final response yet.
+    """
+
+    response: str = Field(
+        description=(
+            "The agent's final response text. Extracted from either a "
+            "FinishAction message or the last agent MessageEvent. "
+            "Empty string if no final response is available."
+        )
+    )
+
+
 class BashEventBase(DiscriminatedUnionMixin, ABC):
     """Base class for all bash event types"""
 

tests/agent_server/test_conversation_response.py

@@ -0,0 +1,183 @@
+"""Tests for the GET /conversations/{id}/agent_final_response endpoint."""
+
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+from uuid import uuid4
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from openhands.agent_server.conversation_router import conversation_router
+from openhands.agent_server.conversation_service import ConversationService
+from openhands.agent_server.dependencies import get_conversation_service
+from openhands.agent_server.event_service import EventService
+from openhands.sdk import Message
+from openhands.sdk.event import ActionEvent, MessageEvent
+from openhands.sdk.llm import MessageToolCall, TextContent
+from openhands.sdk.tool.builtins.finish import FinishAction
+
+
+@pytest.fixture
+def client():
+    app = FastAPI()
+    app.include_router(conversation_router, prefix="/api")
+    return TestClient(app)
+
+
+@pytest.fixture
+def sample_conversation_id():
+    return uuid4()
+
+
+@pytest.fixture
+def mock_conversation_service():
+    return AsyncMock(spec=ConversationService)
+
+
+@pytest.fixture
+def mock_event_service():
+    return AsyncMock(spec=EventService)
+
+
+def test_get_response_with_finish_action(
+    client, mock_conversation_service, mock_event_service, sample_conversation_id
+):
+    """Endpoint returns FinishAction message text."""
+    mock_conversation_service.get_event_service.return_value = mock_event_service
+    mock_event_service.get_agent_final_response.return_value = (
+        "Task completed successfully!"
+    )
+
+    client.app.dependency_overrides[get_conversation_service] = (
+        lambda: mock_conversation_service
+    )
+
+    try:
+        response = client.get(
+            f"/api/conversations/{sample_conversation_id}/agent_final_response"
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["response"] == "Task completed successfully!"
+        mock_conversation_service.get_event_service.assert_called_once_with(
+            sample_conversation_id
+        )
+        mock_event_service.get_agent_final_response.assert_called_once()
+    finally:
+        client.app.dependency_overrides.clear()
+
+
+def test_get_response_empty_when_no_agent_events(
+    client, mock_conversation_service, mock_event_service, sample_conversation_id
+):
+    """Endpoint returns empty string when no agent response exists."""
+    mock_conversation_service.get_event_service.return_value = mock_event_service
+    mock_event_service.get_agent_final_response.return_value = ""
+
+    client.app.dependency_overrides[get_conversation_service] = (
+        lambda: mock_conversation_service
+    )
+
+    try:
+        response = client.get(
+            f"/api/conversations/{sample_conversation_id}/agent_final_response"
+        )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert data["response"] == ""
+    finally:
+        client.app.dependency_overrides.clear()
+
+
+def test_get_response_conversation_not_found(
+    client, mock_conversation_service, sample_conversation_id
+):
+    """Endpoint returns 404 when conversation does not exist."""
+    mock_conversation_service.get_event_service.return_value = None
+
+    client.app.dependency_overrides[get_conversation_service] = (
+        lambda: mock_conversation_service
+    )
+
+    try:
+        response = client.get(
+            f"/api/conversations/{sample_conversation_id}/agent_final_response"
+        )
+        assert response.status_code == 404
+    finally:
+        client.app.dependency_overrides.clear()
+
+
+def test_event_service_get_agent_final_response_with_finish():
+    """EventService delegates to get_agent_final_response from SDK."""
+    event_service = EventService(stored=MagicMock(), conversations_dir=Path("test_dir"))
+
+    finish_action = FinishAction(message="Done!")
+    tool_call = MessageToolCall(
+        id="tc1", name="finish", arguments="{}", origin="completion"
+    )
+    action_event = ActionEvent(
+        source="agent",
+        thought=[TextContent(text="Finishing")],
+        action=finish_action,
+        tool_name="finish",
+        tool_call_id="tc1",
+        tool_call=tool_call,
+        llm_response_id="resp1",
+    )
+
+    conversation = MagicMock()
+    state = MagicMock()
+    state.events = [action_event]
+    conversation._state = state
+    event_service._conversation = conversation
+
+    result = event_service._get_agent_final_response_sync()
+    assert result == "Done!"
+
+
+def test_event_service_get_agent_final_response_with_message():
+    """EventService returns MessageEvent text when no FinishAction."""
+    event_service = EventService(stored=MagicMock(), conversations_dir=Path("test_dir"))
+
+    message_event = MessageEvent(
+        source="agent",
+        llm_message=Message(
+            role="assistant",
+            content=[TextContent(text="Here is my answer")],
+        ),
+    )
+
+    conversation = MagicMock()
+    state = MagicMock()
+    state.events = [message_event]
+    conversation._state = state
+    event_service._conversation = conversation
+
+    result = event_service._get_agent_final_response_sync()
+    assert result == "Here is my answer"
+
+
+def test_event_service_get_agent_final_response_empty():
+    """EventService returns empty string with no agent events."""
+    event_service = EventService(stored=MagicMock(), conversations_dir=Path("test_dir"))
+
+    conversation = MagicMock()
+    state = MagicMock()
+    state.events = []
+    conversation._state = state
+    event_service._conversation = conversation
+
+    result = event_service._get_agent_final_response_sync()
+    assert result == ""
+
+
+def test_event_service_get_agent_final_response_inactive():
+    """EventService raises ValueError when service is inactive."""
+    event_service = EventService(stored=MagicMock(), conversations_dir=Path("test_dir"))
+
+    with pytest.raises(ValueError, match="inactive_service"):
+        event_service._get_agent_final_response_sync()