Add source parameter to /search endpoint for event filtering (#1224)

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

Author: malhotra5

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

@@ -73,6 +73,14 @@ async def search_conversation_events(
             title="Optional filter by event kind/type (e.g., ActionEvent, MessageEvent)"
         ),
     ] = None,
+    source: Annotated[
+        str | None,
+        Query(title="Optional filter by event source (e.g., agent, user, environment)"),
+    ] = None,
+    body: Annotated[
+        str | None,
+        Query(title="Optional filter by message content (case-insensitive)"),
+    ] = None,
     sort_order: Annotated[
         EventSortOrder,
         Query(title="Sort order for events"),
@@ -102,7 +110,7 @@ async def search_conversation_events(
     )
 
     return await event_service.search_events(
-        page_id, limit, kind, sort_order, normalized_gte, normalized_lt
+        page_id, limit, kind, source, body, sort_order, normalized_gte, normalized_lt
     )
 
 
@@ -114,6 +122,14 @@ async def count_conversation_events(
             title="Optional filter by event kind/type (e.g., ActionEvent, MessageEvent)"
         ),
     ] = None,
+    source: Annotated[
+        str | None,
+        Query(title="Optional filter by event source (e.g., agent, user, environment)"),
+    ] = None,
+    body: Annotated[
+        str | None,
+        Query(title="Optional filter by message content (case-insensitive)"),
+    ] = None,
     timestamp__gte: Annotated[
         datetime | None,
         Query(title="Filter: event timestamp >= this datetime"),
@@ -135,7 +151,9 @@ async def count_conversation_events(
         normalize_datetime_to_server_timezone(timestamp__lt) if timestamp__lt else None
     )
 
-    count = await event_service.count_events(kind, normalized_gte, normalized_lt)
+    count = await event_service.count_events(
+        kind, source, body, normalized_gte, normalized_lt
+    )
 
     return count
 

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

@@ -86,6 +86,8 @@ async def search_events(
         page_id: str | None = None,
         limit: int = 100,
         kind: str | None = None,
+        source: str | None = None,
+        body: str | None = None,
         sort_order: EventSortOrder = EventSortOrder.TIMESTAMP,
         timestamp__gte: datetime | None = None,
         timestamp__lt: datetime | None = None,
@@ -109,6 +111,15 @@ async def search_events(
                 ):
                     continue
 
+                # Apply source filter if provided
+                if source is not None and event.source != source:
+                    continue
+
+                # Apply body filter if provided (case-insensitive substring match)
+                if body is not None:
+                    if not self._event_matches_body(event, body):
+                        continue
+
                 # Apply timestamp filters if provided (ISO string comparison)
                 if (
                     timestamp_gte_str is not None
@@ -152,6 +163,8 @@ async def search_events(
     async def count_events(
         self,
         kind: str | None = None,
+        source: str | None = None,
+        body: str | None = None,
         timestamp__gte: datetime | None = None,
         timestamp__lt: datetime | None = None,
     ) -> int:
@@ -174,6 +187,15 @@ async def count_events(
                 ):
                     continue
 
+                # Apply source filter if provided
+                if source is not None and event.source != source:
+                    continue
+
+                # Apply body filter if provided (case-insensitive substring match)
+                if body is not None:
+                    if not self._event_matches_body(event, body):
+                        continue
+
                 # Apply timestamp filters if provided (ISO string comparison)
                 if (
                     timestamp_gte_str is not None
@@ -187,6 +209,32 @@ async def count_events(
 
         return count
 
+    def _event_matches_body(self, event: Event, body: str) -> bool:
+        """Check if event's message content matches body filter (case-insensitive)."""
+        # Import here to avoid circular imports
+        from openhands.sdk.event.llm_convertible.message import MessageEvent
+        from openhands.sdk.llm.message import content_to_str
+
+        # Only check MessageEvent instances for body content
+        if not isinstance(event, MessageEvent):
+            return False
+
+        # Extract text content from the message
+        text_parts = content_to_str(event.llm_message.content)
+
+        # Also check extended content if present
+        if event.extended_content:
+            extended_text_parts = content_to_str(event.extended_content)
+            text_parts.extend(extended_text_parts)
+
+        # Also check reasoning content if present
+        if event.reasoning_content:
+            text_parts.append(event.reasoning_content)
+
+        # Combine all text content and perform case-insensitive substring match
+        full_text = " ".join(text_parts).lower()
+        return body.lower() in full_text
+
     async def batch_get_events(self, event_ids: list[str]) -> list[Event | None]:
         """Given a list of ids, get events (Or none for any which were not found)"""
         results = await asyncio.gather(