Web Search Environment

A web search environment that searches the web with Google Search API (via Serper.dev).

Prerequisites

API Key Setup

This environment requires a Serper.dev API key to function.

Get your API Key:
- Visit Serper.dev and sign up for an account
- Navigate to your dashboard to get your API key
- Free tier includes 2,500 free searches
Configure the API Key:

For Local Development:
```
export SERPER_API_KEY="your-api-key-here"
```
For Docker:
```
docker run -e SERPER_API_KEY="your-api-key-here" web_search-env:latest
```
For Hugging Face Spaces: pass it as a secret when you push (see Deploying to Hugging Face Spaces), or add a SERPER_API_KEY secret in the Space settings.

Important: Never commit your API key to code. Always use environment variables or secrets management.

Quick Start

The simplest way to use the Web Search environment is through the WebSearchEnv client:

from envs.websearch_env import WebSearchAction, WebSearchEnv

try:
    # Create environment from Docker image
    web_search_env = WebSearchEnv.from_docker_image("web_search-env:latest").sync()

    # Reset
    result = web_search_env.reset()
    print(f"Reset: {result.observation.content}")

    # Send a search query
    query = "What is the capital of China?"

    result = web_search_env.step(WebSearchAction(query=query))
    print(f"Formatted search result:", result.observation.content)
    print(f"Individual web contents:", result.observation.web_contents)

finally:
    # Always clean up
    web_search_env.close()

That’s it! The WebSearchEnv.from_docker_image() method handles:

Starting the Docker container
Waiting for the server to be ready
Connecting to the environment
Container cleanup when you call close()

Building the Docker Image

Before using the environment, you need to build the Docker image:

# From the websearch_env directory
cd envs/websearch_env
docker build -t web_search-env:latest -f server/Dockerfile .

Deploying to Hugging Face Spaces

From envs/websearch_env/:

openenv push --repo-id my-org/websearch-env --secret SERPER_API_KEY=your-api-key-here

The environment doesn’t work without SERPER_API_KEY. --secret stores it as a Space secret and never logs it. See the openenv push reference for all options. The Space serves the web UI at /web, the API docs at /docs and a health check at /health.

Environment Details

Action

WebSearchAction: Contains a single field

query (str) - The query to search for
temp_api_key (str) - Temporary Serper.dev API key if not set in environment variables.

Observation

WebSearchObservation: Contains the echo response and metadata

content (str) - The formatted prompt that aggregates both query and web contents
web_contents (list) - List of web contents for top ranked web pages
reward (float) - Not computed (see Reward)
done (bool) - Always False for search environment
metadata (dict) - Additional info like step count

Reward

The environment doesn’t compute a reward. reward is 0.0 after reset() and None after each step.

Advanced Usage

Connecting to an Existing Server

If you already have a Web Search environment server running, you can connect directly:

from envs.websearch_env import WebSearchAction, WebSearchEnv

# Connect to existing server
web_search_env = WebSearchEnv(base_url="<ENV_HTTP_URL_HERE>")

# Use as normal
result = web_search_env.reset()
result = web_search_env.step(WebSearchAction(query="What is the capital of China?"))

Note: When connecting to an existing server, web_search_env.close() will NOT stop the server.

Running Locally

# Make sure to set your API key first
export SERPER_API_KEY="your-api-key-here"

# Then run the server
uvicorn server.app:app --reload

Update on GitHub

OpenEnv