Use SearchConfig for configuration instead of environment variables

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

.github/workflows/deploy-docs.yml

@@ -11,6 +11,7 @@ on:
     paths:
       - 'docs/**'
       - '.github/workflows/deploy-docs.yml'
+      - 'pydoc-markdown.yml'
     branches:
       - main
 
@@ -39,7 +40,10 @@ jobs:
         with:
           python-version: '3.12'
       - name: Generate Python Docs
-        run: rm -rf docs/modules/python && pip install pydoc-markdown && pydoc-markdown
+        run: |
+          rm -rf docs/modules/python
+          pip install pydoc-markdown
+          pydoc-markdown
       - name: Install dependencies
         run: cd docs && npm ci
       - name: Build website

docs/modules/usage/configuration-options.md

@@ -308,6 +308,11 @@ The agent configuration options are defined in the `[agent]` and `[agent.<agent_
   - Default: `false`
   - Description: Whether Jupyter is enabled in the action space
 
+- `enable_search_engine`
+  - Type: `bool`
+  - Default: `false`
+  - Description: Whether the search engine tool is enabled in the action space. See [Search Configuration](./search/search-configuration.md) for details.
+
 - `enable_history_truncation`
   - Type: `bool`
   - Default: `true`

docs/modules/usage/search/search-configuration.md

@@ -0,0 +1,113 @@
+# Search Configuration
+
+OpenHands provides a search engine capability that allows agents to perform web searches using the Brave Search API. This guide explains how to configure and use the search feature.
+
+## Overview
+
+The search engine feature enables agents to:
+- Execute web search queries programmatically
+- Get structured results including web pages, news, videos, and FAQs
+- Avoid CAPTCHA challenges that often occur when using browser-based search
+
+## Configuration
+
+### Enabling Search
+
+To enable the search engine feature, set the following in your `config.toml`:
+
+```toml
+[agent]
+enable_search_engine = true
+```
+
+Or when using Docker, set the environment variable:
+```bash
+-e AGENT_ENABLE_SEARCH_ENGINE=true
+```
+
+### API Key Setup
+
+The search feature requires a Brave Search API key. You can obtain one from the [Brave Search API Dashboard](https://api.search.brave.com/app/keys).
+
+Set the API key in your `config.toml`:
+```toml
+[search]
+enabled = true
+api_key = "your-api-key-here"
+```
+
+Or when using Docker:
+```bash
+-e SEARCH_ENABLED=true
+-e SEARCH_API_KEY="your-api-key-here"
+```
+
+## Search Results
+
+When a search is performed, the results are returned in a structured format that includes:
+
+- Web search results
+- News articles
+- Video content
+- FAQ entries
+- Discussion threads
+- Infoboxes (when available)
+- Location information (when relevant)
+
+Each result type includes:
+- Title
+- URL (when applicable)
+- Description or snippet
+- Additional metadata specific to the result type
+
+## Usage Example
+
+When the search feature is enabled, agents can use the `search_engine` tool to perform searches. For example:
+
+```python
+# The agent can make a tool call like this:
+{
+    "name": "search_engine",
+    "arguments": {
+        "query": "latest developments in AI"
+    }
+}
+```
+
+The search results will be returned in a markdown-formatted structure that's easy for the agent to parse and understand.
+
+## Best Practices
+
+1. **Query Formulation**
+   - Keep queries focused and specific
+   - Include relevant keywords
+   - Avoid overly complex or compound queries
+
+2. **Rate Limiting**
+   - Be mindful of API rate limits
+   - Cache results when appropriate
+   - Implement retries with exponential backoff for failed requests
+
+3. **Error Handling**
+   - Handle API errors gracefully
+   - Provide meaningful feedback when searches fail
+   - Have fallback strategies when search is unavailable
+
+## Troubleshooting
+
+Common issues and solutions:
+
+1. **Search Not Working**
+   - Verify `enable_search_engine` is set to `true`
+   - Confirm the Brave API key is correctly set
+   - Check API key permissions and quotas
+
+2. **No Results**
+   - Verify the query is not empty
+   - Try reformulating the search query
+   - Check for any API response errors
+
+3. **Rate Limiting**
+   - Monitor API usage
+   - Implement caching if needed
+   - Consider upgrading API tier if limits are consistently hit

openhands/agenthub/codeact_agent/codeact_agent.py

@@ -70,6 +70,7 @@ class CodeActAgent(Agent):
             codeact_enable_browsing=self.config.codeact_enable_browsing,
             codeact_enable_jupyter=self.config.codeact_enable_jupyter,
             codeact_enable_llm_editor=self.config.codeact_enable_llm_editor,
+            codeact_enable_search_engine=self.config.enable_search_engine,
             llm=self.llm,
         )
         logger.debug(

openhands/agenthub/codeact_agent/function_calling.py

@@ -15,6 +15,7 @@ from openhands.agenthub.codeact_agent.tools import (
     FinishTool,
     IPythonTool,
     LLMBasedFileEditTool,
+    SearchEngineTool,
     ThinkTool,
     WebReadTool,
     create_cmd_run_tool,
@@ -36,6 +37,7 @@ from openhands.events.action import (
     FileReadAction,
     IPythonRunCellAction,
     MessageAction,
+    SearchAction,
 )
 from openhands.events.event import FileEditSource, FileReadSource
 from openhands.events.tool import ToolCallMetadata
@@ -191,6 +193,15 @@ def response_to_actions(response: ModelResponse) -> list[Action]:
                         f'Missing required argument "url" in tool call {tool_call.function.name}'
                     )
                 action = BrowseURLAction(url=arguments['url'])
+            # ================================================
+            # SearchEngineTool (search the web using text queries)
+            # ================================================
+            elif tool_call.function.name == SearchEngineTool['function']['name']:
+                if 'query' not in arguments:
+                    raise FunctionCallNotExistsError(
+                        f'Missing required argument "query" in tool call {tool_call.function.name}'
+                    )
+                action = SearchAction(query=arguments['query'])
             else:
                 raise FunctionCallNotExistsError(
                     f'Tool {tool_call.function.name} is not registered. (arguments: {arguments}). Please check the tool name and retry with an existing tool.'
@@ -223,6 +234,7 @@ def get_tools(
     codeact_enable_browsing: bool = False,
     codeact_enable_llm_editor: bool = False,
     codeact_enable_jupyter: bool = False,
+    codeact_enable_search_engine: bool = False,
     llm: LLM | None = None,
 ) -> list[ChatCompletionToolParam]:
     SIMPLIFIED_TOOL_DESCRIPTION_LLM_SUBSTRS = ['gpt-', 'o3', 'o1']
@@ -239,6 +251,8 @@ def get_tools(
         ThinkTool,
         FinishTool,
     ]
+    if codeact_enable_search_engine:
+        tools.append(SearchEngineTool)
     if codeact_enable_browsing:
         tools.append(WebReadTool)
         tools.append(BrowserTool)

openhands/agenthub/codeact_agent/tools/__init__.py

@@ -3,6 +3,7 @@ from .browser import BrowserTool
 from .finish import FinishTool
 from .ipython import IPythonTool
 from .llm_based_edit import LLMBasedFileEditTool
+from .search_engine import SearchEngineTool
 from .str_replace_editor import create_str_replace_editor_tool
 from .think import ThinkTool
 from .web_read import WebReadTool
@@ -13,6 +14,7 @@ __all__ = [
     'FinishTool',
     'IPythonTool',
     'LLMBasedFileEditTool',
+    'SearchEngineTool',
     'create_str_replace_editor_tool',
     'WebReadTool',
     'ThinkTool',

openhands/agenthub/codeact_agent/tools/search_engine.py

@@ -0,0 +1,24 @@
+from litellm import ChatCompletionToolParam, ChatCompletionToolParamFunctionChunk
+
+_SEARCH_ENGINE_DESCRIPTION = """Execute a web search query (similar to Google search).
+
+NOTE: When you need to search for information online, please use the `search_engine` tool rather than the `browser` or `web_read` tools. The `search_engine` tool connects directly to a search engine, which will help avoid CAPTCHA challenges that would otherwise block your access.
+"""
+
+SearchEngineTool = ChatCompletionToolParam(
+    type='function',
+    function=ChatCompletionToolParamFunctionChunk(
+        name='search_engine',
+        description=_SEARCH_ENGINE_DESCRIPTION,
+        parameters={
+            'type': 'object',
+            'properties': {
+                'query': {
+                    'type': 'string',
+                    'description': 'The web search query (must be a non-empty string).',
+                },
+            },
+            'required': ['query'],
+        },
+    ),
+)

openhands/core/config/__init__.py

@@ -8,6 +8,7 @@ from openhands.core.config.config_utils import (
 from openhands.core.config.extended_config import ExtendedConfig
 from openhands.core.config.llm_config import LLMConfig
 from openhands.core.config.sandbox_config import SandboxConfig
+from openhands.core.config.search_config import SearchConfig
 from openhands.core.config.security_config import SecurityConfig
 from openhands.core.config.utils import (
     finalize_config,
@@ -28,6 +29,7 @@ __all__ = [
     'AppConfig',
     'LLMConfig',
     'SandboxConfig',
+    'SearchConfig',
     'SecurityConfig',
     'ExtendedConfig',
     'load_app_config',

openhands/core/config/agent_config.py

@@ -2,7 +2,10 @@ from __future__ import annotations
 
 from pydantic import BaseModel, Field, ValidationError
 
-from openhands.core.config.condenser_config import CondenserConfig, NoOpCondenserConfig
+from openhands.core.config.condenser_config import (
+    CondenserConfig,
+    NoOpCondenserConfig,
+)
 from openhands.core.logger import openhands_logger as logger
 
 
@@ -30,6 +33,7 @@ class AgentConfig(BaseModel):
     disabled_microagents: list[str] = Field(default_factory=list)
     enable_history_truncation: bool = Field(default=True)
     enable_som_visual_browsing: bool = Field(default=False)
+    enable_search_engine: bool = Field(default=False)
     condenser: CondenserConfig = Field(default_factory=NoOpCondenserConfig)
 
     model_config = {'extra': 'forbid'}

openhands/core/config/app_config.py

@@ -12,6 +12,7 @@ from openhands.core.config.config_utils import (
 from openhands.core.config.extended_config import ExtendedConfig
 from openhands.core.config.llm_config import LLMConfig
 from openhands.core.config.sandbox_config import SandboxConfig
+from openhands.core.config.search_config import SearchConfig
 from openhands.core.config.security_config import SecurityConfig
 
 
@@ -53,6 +54,7 @@ class AppConfig(BaseModel):
     default_agent: str = Field(default=OH_DEFAULT_AGENT)
     sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
     security: SecurityConfig = Field(default_factory=SecurityConfig)
+    search: SearchConfig = Field(default_factory=SearchConfig)
     extended: ExtendedConfig = Field(default_factory=lambda: ExtendedConfig({}))
     runtime: str = Field(default='docker')
     file_store: str = Field(default='local')

openhands/core/config/search_config.py

@@ -0,0 +1,35 @@
+"""Configuration for search engine functionality."""
+
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretStr
+
+
+class SearchConfig(BaseModel):
+    """Configuration for search engine functionality.
+
+    Attributes:
+        enabled: Whether search engine functionality is enabled.
+        api_key: The API key for the search engine.
+        api_url: The base URL for the search API.
+    """
+
+    enabled: bool = Field(default=False)
+    api_key: SecretStr | None = Field(default=None)
+    api_url: str = Field(default="https://api.search.brave.com/res/v1/web/search")
+
+    model_config = {"extra": "forbid"}
+
+    def model_post_init(self, __context: Any) -> None:
+        """Post-initialization hook to assign search-related variables to environment variables.
+
+        This ensures that these values are accessible to the search engine at runtime.
+        """
+        super().model_post_init(__context)
+
+        # Set environment variables for search engine
+        if self.api_key:
+            os.environ["BRAVE_API_KEY"] = self.api_key.get_secret_value()
+        if self.api_url:
+            os.environ["BRAVE_API_URL"] = self.api_url

openhands/core/schema/action.py

@@ -82,6 +82,9 @@ class ActionTypeSchema(BaseModel):
     SEND_PR: str = Field(default='send_pr')
     """Send a PR to github."""
 
+    SEARCH: str = Field(default='search')
+    """Queries a search engine."""
+
     RECALL: str = Field(default='recall')
     """Retrieves content from a user workspace, microagent, or other source."""
 

openhands/core/schema/observation.py

@@ -49,6 +49,9 @@ class ObservationTypeSchema(BaseModel):
     CONDENSE: str = Field(default='condense')
     """Result of a condensation operation."""
 
+    SEARCH: str = Field(default='search')
+    """Result of querying a search engine."""
+
     RECALL: str = Field(default='recall')
     """Result of a recall operation. This can be the workspace context, a microagent, or other types of information."""
 

openhands/events/action/__init__.py

@@ -17,6 +17,7 @@ from openhands.events.action.files import (
     FileWriteAction,
 )
 from openhands.events.action.message import MessageAction
+from openhands.events.action.search_engine import SearchAction
 
 __all__ = [
     'Action',
@@ -36,5 +37,6 @@ __all__ = [
     'MessageAction',
     'ActionConfirmationStatus',
     'AgentThinkAction',
+    'SearchAction',
     'RecallAction',
 ]

openhands/events/action/search_engine.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+from typing import ClassVar
+
+from openhands.core.schema import ActionType
+from openhands.events.action.action import Action
+
+
+@dataclass
+class SearchAction(Action):
+    query: str
+    thought: str = ''
+    action: str = ActionType.SEARCH
+    runnable: ClassVar[bool] = True
+
+    @property
+    def message(self) -> str:
+        return f'I am querying the search engine to search for {self.query}'
+
+    def __str__(self) -> str:
+        ret = '**SearchAction**\n'
+        if self.thought:
+            ret += f'THOUGHT: {self.thought}\n'
+        ret += f'QUERY: {self.query}'
+        return ret

openhands/events/observation/__init__.py

@@ -5,6 +5,7 @@ from openhands.events.observation.agent import (
     AgentThinkObservation,
     RecallObservation,
 )
+from openhands.events.observation.search_engine import SearchEngineObservation
 from openhands.events.observation.browse import BrowserOutputObservation
 from openhands.events.observation.commands import (
     CmdOutputMetadata,
@@ -42,6 +43,7 @@ __all__ = [
     'SuccessObservation',
     'UserRejectObservation',
     'AgentCondensationObservation',
+    'SearchEngineObservation',
     'RecallObservation',
     'RecallType',
 ]

openhands/events/observation/search_engine.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+
+from openhands.core.schema import ObservationType
+from openhands.events.observation.observation import Observation
+
+
+@dataclass
+class SearchEngineObservation(Observation):
+    query: str
+    observation: str = ObservationType.SEARCH
+
+    @property
+    def message(self) -> str:
+        return f'Searched for: {self.query}'
+
+    def __str__(self) -> str:
+        ret = (
+            '**SearchEngineObservation**\n'
+            f'Query: {self.query}\n'
+            f'Search Results: {self.content}\n'
+        )
+        return ret

openhands/events/serialization/action.py

@@ -22,6 +22,7 @@ from openhands.events.action.files import (
     FileWriteAction,
 )
 from openhands.events.action.message import MessageAction
+from openhands.events.action.search_engine import SearchAction
 
 actions = (
     NullAction,
@@ -39,6 +40,7 @@ actions = (
     RecallAction,
     ChangeAgentStateAction,
     MessageAction,
+    SearchAction,
 )
 
 ACTION_TYPE_TO_CLASS = {action_class.action: action_class for action_class in actions}  # type: ignore[attr-defined]

openhands/memory/conversation_memory.py

@@ -27,6 +27,7 @@ from openhands.events.observation import (
     FileEditObservation,
     FileReadObservation,
     IPythonRunCellObservation,
+    SearchEngineObservation,
     UserRejectObservation,
 )
 from openhands.events.observation.agent import (
@@ -385,6 +386,9 @@ class ConversationMemory:
         elif isinstance(obs, AgentCondensationObservation):
             text = truncate_content(obs.content, max_message_chars)
             message = Message(role='user', content=[TextContent(text=text)])
+        elif isinstance(obs, SearchEngineObservation):
+            text = truncate_content(obs.content, max_message_chars)
+            message = Message(role='user', content=[TextContent(text=text)])
         elif (
             isinstance(obs, RecallObservation)
             and self.agent_config.enable_prompt_extensions

openhands/runtime/action_execution_server.py

@@ -41,6 +41,7 @@ from openhands.events.action import (
     FileReadAction,
     FileWriteAction,
     IPythonRunCellAction,
+    SearchAction,
 )
 from openhands.events.event import FileEditSource, FileReadSource
 from openhands.events.observation import (
@@ -56,6 +57,7 @@ from openhands.events.serialization import event_from_dict, event_to_dict
 from openhands.runtime.browser import browse
 from openhands.runtime.browser.browser_env import BrowserEnv
 from openhands.runtime.plugins import ALL_PLUGINS, JupyterPlugin, Plugin, VSCodePlugin
+from openhands.runtime.search_engine.brave_search import search
 from openhands.runtime.utils.bash import BashSession
 from openhands.runtime.utils.files import insert_lines, read_lines
 from openhands.runtime.utils.memory_monitor import MemoryMonitor
@@ -163,7 +165,6 @@ class ActionExecutor:
         self.start_time = time.time()
         self.last_execution_time = self.start_time
         self._initialized = False
-
         self.max_memory_gb: int | None = None
         if _override_max_memory_gb := os.environ.get('RUNTIME_MAX_MEMORY_GB', None):
             self.max_memory_gb = int(_override_max_memory_gb)
@@ -464,6 +465,10 @@ class ActionExecutor:
     async def browse_interactive(self, action: BrowseInteractiveAction) -> Observation:
         return await browse(action, self.browser)
 
+    async def search(self, action: SearchAction) -> Observation:
+        obs = await call_sync_from_async(search, action)
+        return obs
+
     def close(self):
         self.memory_monitor.stop_monitoring()
         if self.bash_session is not None:

openhands/runtime/impl/action_execution/action_execution_client.py

@@ -24,6 +24,7 @@ from openhands.events.action import (
     FileReadAction,
     FileWriteAction,
     IPythonRunCellAction,
+    SearchAction,
 )
 from openhands.events.action.action import Action
 from openhands.events.action.files import FileEditSource
@@ -297,6 +298,9 @@ class ActionExecutionClient(Runtime):
     def browse_interactive(self, action: BrowseInteractiveAction) -> Observation:
         return self.send_action_for_execution(action)
 
+    def search(self, action: SearchAction) -> Observation:
+        return self.send_action_for_execution(action)
+
     def close(self) -> None:
         # Make sure we don't close the session multiple times
         # Can happen in evaluation

openhands/runtime/search_engine/__init__.py

@@ -0,0 +1,3 @@
+from openhands.runtime.search_engine.brave_search import search
+
+__all__ = ['search']

openhands/runtime/search_engine/brave_search.py

@@ -0,0 +1,239 @@
+import os
+import re
+
+import requests
+import tenacity
+
+from openhands.core.config import AppConfig
+from openhands.events.action import SearchAction
+from openhands.events.observation.error import ErrorObservation
+from openhands.events.observation.search_engine import SearchEngineObservation
+from openhands.utils.tenacity_stop import stop_if_should_exit
+
+
+def get_title(result):
+    return f"### Title: {result['title']}\n" if 'title' in result else ''
+
+
+def get_url(result):
+    return f"### URL: {result['url']}\n" if 'url' in result else ''
+
+
+def get_description(result):
+    return (
+        f"### Description: {result['description']}\n" if 'description' in result else ''
+    )
+
+
+def get_question(result):
+    return f"### Question: {result['question']}\n" if 'question' in result else ''
+
+
+def get_answer(result):
+    return f"### Answer: {result['answer']}\n" if 'answer' in result else ''
+
+
+def get_cluster(result):
+    if 'cluster' in result:
+        output = ''
+        for i, result_obj in enumerate(result['cluster']):
+            title = get_title(result_obj)
+            url = get_url(result_obj)
+            description = get_description(result_obj)
+            discussion_output = (
+                f'### Related webpage\n#{title}#{url}#{description}\n'
+                if url != ''
+                else ''
+            )
+            output += discussion_output
+        return output
+    else:
+        return ''
+
+
+def response_to_markdown(results, query):
+    all_results = {}
+
+    # discussions
+    discussion_results = []
+    if 'discussions' in results and 'results' in results['discussions']['results']:
+        for result in results['discussions']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            description = get_description(result)
+            cluster = get_cluster(result)
+            discussion_output = f'## Discussion\n{title}{url}{description}{cluster}\n'
+            discussion_results.append(discussion_output)
+    all_results['discussions'] = discussion_results
+
+    # FAQs
+    faq_results = []
+    if 'faq' in results and 'results' in results['faq']:
+        for result in results['faq']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            question = get_question(result)
+            answer = get_answer(result)
+            faq_output = f'## FAQ\n{title}{url}{question}{answer}\n'
+            faq_results.append(faq_output)
+    all_results['faq'] = faq_results
+
+    # News
+    news_results = []
+    if 'news' in results and 'results' in results['news']:
+        for result in results['news']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            description = get_description(result)
+            news_output = f'## News\n{title}{url}{description}\n'
+            news_results.append(news_output)
+    all_results['news'] = news_results
+
+    # Videos
+    video_results = []
+    if 'videos' in results and 'results' in results['videos']:
+        for result in results['videos']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            description = get_description(result)
+            video_output = f'## Video\n{title}{url}{description}\n'
+            video_results.append(video_output)
+    all_results['videos'] = video_results
+
+    # Web Search Results
+    websearch_results = []
+    if 'web' in results and 'results' in results['web']:
+        for result in results['web']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            description = get_description(result)
+            cluster = get_cluster(result)
+            if cluster:
+                websearch_output = f'## Webpage\n{title}{url}{description}\n{cluster}\n'
+            else:
+                websearch_output = f'## Webpage\n{title}{url}{description}\n'
+            websearch_results.append(websearch_output)
+    all_results['web'] = websearch_results
+
+    # infobox
+    infobox_results = []
+    if 'infobox' in results and 'results' in results['infobox']:
+        for result in results['infobox']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            description = get_description(result)
+            infobox_output = f'## Infobox\n{title}{url}{description}\n'
+            infobox_results.append(infobox_output)
+    all_results['infobox'] = infobox_results
+
+    # locations
+    location_results = []
+    if 'locations' in results and 'results' in results['location']:
+        for result in results['locations']['results']:
+            title = get_title(result)
+            url = get_url(result)
+            description = get_description(result)
+            location_output = f'## Location\n{title}{url}{description}\n'
+            location_results.append(location_output)
+    all_results['locations'] = location_results
+
+    markdown = '# Search Results\n\n'
+    markdown += f'**Searched query**: {query}\n\n'
+
+    # ranked results if available
+    if 'mixed' in results:
+        for rank_type in ['main', 'top', 'side']:
+            if rank_type not in results['mixed']:
+                continue
+            for ranked_result in results['mixed'][rank_type]:
+                result_type = ranked_result['type']
+                if result_type in all_results:
+                    include_all = ranked_result['all']
+                    idx = ranked_result.get('index', None)
+                    if include_all:
+                        markdown += ''.join(all_results[result_type])
+                    elif idx is not None and idx < len(all_results[result_type]):
+                        markdown += all_results[result_type][idx]
+        for result_list in all_results.values():
+            for result in result_list:
+                if result in markdown:
+                    continue
+                else:
+                    markdown += result
+    else:
+        markdown += ''.join(
+            websearch_results
+            + video_results
+            + news_results
+            + infobox_results
+            + faq_results
+            + discussion_results
+            + location_results
+        )
+    return markdown
+
+
+def return_error(retry_state: tenacity.RetryCallState):
+    return ErrorObservation('Failed to query Brave Search API.')
+
+
+@tenacity.retry(
+    wait=tenacity.wait_exponential(min=2, max=10),
+    stop=tenacity.stop_after_attempt(5) | stop_if_should_exit(),
+    retry_error_callback=return_error,
+)
+def query_api(query: str, API_KEY, BRAVE_SEARCH_URL):
+    headers = {'Accept': 'application/json', 'X-Subscription-Token': API_KEY}
+
+    params: list[tuple[str, str | int | bool]] = [
+        ('q', query),
+        ('count', 20),  # Number of results to return, max allowed = 20
+        ('extra_snippets', False),  # TODO: Should we keep it as true?
+    ]
+
+    response = requests.get(
+        BRAVE_SEARCH_URL,
+        headers=headers,
+        params=params,  # type: ignore
+        timeout=10,
+    )
+    response.raise_for_status()  # Raise exception for 4XX/5XX responses
+    results = response.json()
+    markdown_content = response_to_markdown(results, query)
+    # TODO: Handle other types of HTML tags? I couldn't find any other tags in brave search responses for the queries I tried.
+    markdown_content = re.sub(r'</?strong>', '', markdown_content)
+    return SearchEngineObservation(query=query, content=markdown_content)
+
+
+def search(action: SearchAction, config: AppConfig):
+    """Execute a search query using the Brave Search API.
+
+    Args:
+        action: The search action containing the query.
+        config: The application configuration.
+
+    Returns:
+        SearchEngineObservation: The search results in markdown format.
+        ErrorObservation: If the query is empty or search is not enabled.
+    """
+    if not config.search.enabled:
+        return ErrorObservation(
+            content='Search engine functionality is not enabled. Enable it by setting search.enabled=true in config.'
+        )
+
+    query = action.query
+    if query is None or len(query.strip()) == 0:
+        return ErrorObservation(
+            content='The query string for search_engine tool must be a non-empty string.'
+        )
+
+    if config.search.api_key is None:
+        return ErrorObservation(
+            content='Search API key not configured. Set search.api_key in config.'
+        )
+
+    return query_api(
+        query=query,
+        API_KEY=config.search.api_key.get_secret_value(),
+        BRAVE_SEARCH_URL=config.search.api_url
+    )

tests/unit/test_brave_search.py

@@ -0,0 +1,83 @@
+"""Tests for the Brave Search functionality."""
+
+from unittest.mock import Mock, patch
+
+import pytest
+
+from openhands.core.config import AppConfig, SearchConfig
+from openhands.events.action import SearchAction
+from openhands.events.observation.error import ErrorObservation
+from openhands.events.observation.search_engine import SearchEngineObservation
+from openhands.runtime.search_engine.brave_search import search
+
+
+@pytest.fixture
+def mock_config():
+    """Create a mock config with search enabled."""
+    config = AppConfig()
+    config.search = SearchConfig(
+        enabled=True,
+        api_key="test_key",
+        api_url="https://test.url"
+    )
+    return config
+
+
+@pytest.fixture
+def mock_query_api():
+    """Create a mock query_api function."""
+    with patch("openhands.runtime.search_engine.brave_search.query_api") as mock:
+        mock.return_value = SearchEngineObservation(
+            query="test query",
+            content="test content"
+        )
+        yield mock
+
+
+def test_search_disabled(mock_query_api):
+    """Test that search returns error when disabled."""
+    config = AppConfig()
+    config.search = SearchConfig(enabled=False)
+    action = SearchAction(query="test query")
+
+    result = search(action, config)
+    assert isinstance(result, ErrorObservation)
+    assert "not enabled" in result.content
+    mock_query_api.assert_not_called()
+
+
+def test_search_no_api_key(mock_query_api):
+    """Test that search returns error when API key is not set."""
+    config = AppConfig()
+    config.search = SearchConfig(enabled=True)
+    action = SearchAction(query="test query")
+
+    result = search(action, config)
+    assert isinstance(result, ErrorObservation)
+    assert "API key not configured" in result.content
+    mock_query_api.assert_not_called()
+
+
+def test_search_empty_query(mock_query_api, mock_config):
+    """Test that search returns error when query is empty."""
+    action = SearchAction(query="")
+
+    result = search(action, mock_config)
+    assert isinstance(result, ErrorObservation)
+    assert "must be a non-empty string" in result.content
+    mock_query_api.assert_not_called()
+
+
+def test_search_success(mock_query_api, mock_config):
+    """Test that search returns results when everything is configured correctly."""
+    action = SearchAction(query="test query")
+
+    result = search(action, mock_config)
+    assert isinstance(result, SearchEngineObservation)
+    assert result.query == "test query"
+    assert result.content == "test content"
+    mock_query_api.assert_called_once_with(
+        query="test query",
+        API_KEY="test_key",
+        BRAVE_SEARCH_URL="https://test.url"
+    )

tests/unit/test_codeact_agent.py

@@ -25,6 +25,7 @@ from openhands.core.message import ImageContent, Message, TextContent
 from openhands.events.action import (
     CmdRunAction,
     MessageAction,
+    SearchAction,
 )
 from openhands.events.event import EventSource
 from openhands.events.observation.commands import (
@@ -100,22 +101,26 @@ def test_get_tools_with_options():
         codeact_enable_browsing=True,
         codeact_enable_jupyter=True,
         codeact_enable_llm_editor=True,
+        codeact_enable_search_engine=True,
     )
     tool_names = [tool['function']['name'] for tool in tools]
     assert 'browser' in tool_names
     assert 'execute_ipython_cell' in tool_names
     assert 'edit_file' in tool_names
+    assert 'search_engine' in tool_names
 
     # Test with all options disabled
     tools = get_tools(
         codeact_enable_browsing=False,
         codeact_enable_jupyter=False,
         codeact_enable_llm_editor=False,
+        codeact_enable_search_engine=False,
     )
     tool_names = [tool['function']['name'] for tool in tools]
     assert 'browser' not in tool_names
     assert 'execute_ipython_cell' not in tool_names
     assert 'edit_file' not in tool_names
+    assert 'search_engine' not in tool_names
 
 
 def test_cmd_run_tool():
@@ -176,6 +181,15 @@ def test_web_read_tool():
     assert WebReadTool['function']['parameters']['required'] == ['url']
 
 
+def test_search_engine_tool():
+    from openhands.agenthub.codeact_agent.tools import SearchEngineTool
+
+    assert SearchEngineTool['type'] == 'function'
+    assert SearchEngineTool['function']['name'] == 'search_engine'
+    assert 'query' in SearchEngineTool['function']['parameters']['properties']
+    assert SearchEngineTool['function']['parameters']['required'] == ['query']
+
+
 def test_browser_tool():
     assert BrowserTool['type'] == 'function'
     assert BrowserTool['function']['name'] == 'browser'
@@ -212,6 +226,42 @@ def test_browser_tool():
     assert 'description' in BrowserTool['function']['parameters']['properties']['code']
 
 
+def test_response_to_actions_search_engine():
+    # Test response with search engine tool call
+    from litellm import ChatCompletionMessageToolCall, Choices, Message, ModelResponse
+
+    mock_response = ModelResponse(
+        id='mock_id',
+        choices=[
+            Choices(
+                message=Message(
+                    content='Let me search for that',
+                    tool_calls=[
+                        ChatCompletionMessageToolCall(
+                            id='tool_call_10',
+                            function={
+                                'name': 'search_engine',
+                                'arguments': '{"query": "test query"}',
+                            },
+                            type='function',
+                        )
+                    ],
+                    role='assistant',
+                ),
+                index=0,
+                finish_reason='tool_calls',
+            )
+        ],
+        model='mock_model',
+        usage={'total_tokens': 100},
+    )
+
+    actions = response_to_actions(mock_response)
+    assert len(actions) == 1
+    assert isinstance(actions[0], SearchAction)
+    assert actions[0].query == 'test query'
+
+
 def test_response_to_actions_invalid_tool():
     # Test response with invalid tool call
     mock_response = Mock()