π OpenHands: AI-Driven Development
Add search engine setup documentation (#8870)
Xingyao Wang2f55cbb74835
diff --git a/docs/docs.json b/docs/docs.jsonindex 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.mdxindex 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).#### Versionsdiff --git a/docs/usage/search-engine-setup.mdx b/docs/usage/search-engine-setup.mdxnew file mode 100644index 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