Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Add search engine setup documentation (#8870)

Xingyao Wang2f55cbb74835
diff --git a/docs/docs.json b/docs/docs.json
index 5b2ba37e40..4a7fcde553 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -116,6 +116,7 @@
},
"usage/configuration-options",
"usage/how-to/custom-sandbox-guide",
+ "usage/search-engine-setup",
"usage/mcp"
]
},
diff --git a/docs/usage/installation.mdx b/docs/usage/installation.mdx
index ced1ab81b9..99d077c946 100644
--- a/docs/usage/installation.mdx
+++ b/docs/usage/installation.mdx
@@ -17,6 +17,7 @@ You'll be prompted to connect with your GitHub or GitLab account:
- OpenHands will require certain permissions from your account. To read more about these permissions,
you can click the `Learn more` link on the authorization page.
+
Once you've connected your account, you can:
- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories
@@ -139,11 +140,24 @@ Consider setting usage limits to control costs.
2. [Generate an API key](https://platform.openai.com/api-keys).
3. [Set up billing](https://platform.openai.com/account/billing/overview).
-
</Accordion>
</AccordionGroup>
+#### Setting Up Search Engine
+
+OpenHands can be configured to use a search engine to allow the agent to search the web for information when needed.
+
+Search functionality is enabled by default in OpenHands Cloud. No additional setup is required.
+
+To enable search functionality in self-hosted OpenHands:
+
+1. Get a Tavily API key from [tavily.com](https://tavily.com/)
+2. Enter the API key in the Settings page under `LLM` tab, `Search API Key (Tavily)`
+
+For more details, see the [Search Engine Setup](/usage/search-engine-setup) guide.
+
+
Now you're ready to [get started with OpenHands](./getting-started).
#### Versions
diff --git a/docs/usage/search-engine-setup.mdx b/docs/usage/search-engine-setup.mdx
new file mode 100644
index 0000000000..830372f95a
--- /dev/null
+++ b/docs/usage/search-engine-setup.mdx
@@ -0,0 +1,66 @@
+---
+title: Search Engine Setup
+description: Configure OpenHands to use Tavily as a search engine
+---
+
+## Setting Up Search Engine in OpenHands
+
+OpenHands can be configured to use [Tavily](https://tavily.com/) as a search engine, which allows the agent to search the web for information when needed. This capability enhances the agent's ability to provide up-to-date information and solve problems that require external knowledge.
+
+### Getting a Tavily API Key
+
+To use the search functionality in OpenHands, you'll need to obtain a Tavily API key:
+
+1. Visit [Tavily's website](https://tavily.com/) and sign up for an account
+2. Navigate to the API section in your dashboard
+3. Generate a new API key
+4. Copy the API key (it should start with `tvly-`)
+
+### Configuring Search in OpenHands
+
+Once you have your Tavily API key, you can configure OpenHands to use it:
+
+#### In the OpenHands UI
+
+1. Open OpenHands and navigate to the Settings page by clicking the gear icon
+2. In the LLM settings tab, locate the "Search API Key (Tavily)" field
+3. Enter your Tavily API key (starting with `tvly-`)
+4. Click "Save" to apply the changes
+
+<Note>
+The search API key field is optional. If you don't provide a key, the search functionality will not be available to the agent.
+</Note>
+
+#### Using Configuration Files
+
+If you're running OpenHands in headless mode or via CLI, you can configure the search API key in your configuration file:
+
+```toml
+# In your OpenHands config file
+[core]
+search_api_key = "tvly-your-api-key-here"
+```
+
+### How Search Works in OpenHands
+
+When the search engine is configured:
+
+1. The agent can decide to search the web when it needs external information
+2. Search queries are sent to Tavily's API via [Tavily's MCP server](https://github.com/tavily-ai/tavily-mcp) which includes a variety of [tools](https://docs.tavily.com/documentation/api-reference/introduction) (search, extract, crawl, map).
+3. Results are returned and incorporated into the agent's context
+4. The agent can use this information to provide more accurate and up-to-date responses
+
+### Limitations
+
+- Search results depend on Tavily's coverage and freshness
+- Usage may be subject to Tavily's rate limits and pricing tiers
+- The agent will only search when it determines that external information is needed
+
+### Troubleshooting
+
+If you encounter issues with the search functionality:
+
+- Verify that your API key is correct and active
+- Check that your API key starts with `tvly-`
+- Ensure you have an active internet connection
+- Check Tavily's status page for any service disruptions