dsh-agent-web-search

Configuration

Configuration is read from environment variables when the CLI, MCP server, or Hermes plugin starts. Restart the process after changing provider settings. See .env.example for a commented template of every variable.

General settings

Variable	Default	Purpose
AGENT_WEB_SEARCH_PROVIDERS	ddgs,exa,parallel	Comma-separated startup-enabled provider set
AGENT_WEB_SEARCH_TIMEOUT	60	Socket timeout for a single upstream HTTP call. Multi-step providers multiply it: keyless Parallel makes up to 3 calls (worst case 3×), ARK may append a continuation call (worst case 2×), so the whole search can take up to 3 × this value

Example:

export AGENT_WEB_SEARCH_PROVIDERS="ddgs,exa,brave"
export AGENT_WEB_SEARCH_TIMEOUT="30"

$env:AGENT_WEB_SEARCH_PROVIDERS = "ddgs,exa,brave"
$env:AGENT_WEB_SEARCH_TIMEOUT = "30"

HTTP transport settings

Variable	Default	Purpose
AGENT_WEB_SEARCH_MCP_TRANSPORT	stdio	stdio or http; --transport may override it
AGENT_WEB_SEARCH_HTTP_HOST	0.0.0.0	HTTP bind host for container deployments
AGENT_WEB_SEARCH_HTTP_PORT	PORT or 8000	HTTP bind port; explicit value overrides platform PORT
AGENT_WEB_SEARCH_AUTH_TOKEN	—	Required HTTP Bearer Token, at least 32 characters
AGENT_WEB_SEARCH_ALLOW_ANONYMOUS	false	Explicitly disables HTTP auth for trusted/demo environments
AGENT_WEB_SEARCH_HTTP_ALLOWED_HOSTS	—	Optional comma-separated Host allowlist
AGENT_WEB_SEARCH_HTTP_ALLOWED_ORIGINS	—	Optional comma-separated Origin allowlist; requires allowed hosts
AGENT_WEB_SEARCH_HTTP_LOG_LEVEL	info	Uvicorn log level for the container server

HTTP settings remain environment-only; the deployment files do not introduce a second application configuration format.

Provider settings

Provider-specific settings below include the credential and model controls for all providers. The supported-provider overview above is grouped by capability; this section is the detailed configuration reference.

1. DDGS

DDGS uses DuckDuckGo and requires no API key or provider-specific environment variables. The ddgs Python dependency is installed with the package.

2. Exa

Exa supports both paid and keyless modes.

Variable	Required	Purpose
EXA_API_KEY	No	Uses the paid Search API when present
EXA_MCP_URL	No	Overrides the free MCP endpoint when no API key is set

Without EXA_API_KEY, Exa falls back to its free MCP endpoint on a best-effort basis. The paid API generally provides higher quota and reliability.

3. Parallel

Parallel returns information-dense excerpts ranked for LLM context. One parallel provider automatically selects its transport:

• Without a key, it uses Parallel's free Search MCP.
• With PARALLEL_API_KEY, it uses the paid Search REST API.

Both transports map excerpts into the common result description, so the calling agent does not need to distinguish parallel-free from parallel.

Variable	Required	Purpose
PARALLEL_API_KEY	No	Enables the paid API; omit it to use the free MCP

Parallel is enabled by default and its key is optional.

4. ARK (Recommended)

Volcengine ARK uses model-backed search grounding through the Responses API. Add ark to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

Variable	Required	Purpose
ARK_API_KEY	Yes	One key, or multiple comma/newline-separated keys
AGENT_WEB_SEARCH_ARK_MODELS	No	Comma/newline-separated ARK model IDs

One model stays fixed; multiple models are selected round-robin for successive requests. When multiple ARK keys are configured, a key is selected per request.

Optional Volcengine collaboration rewards information

Agent Web Search does not require participation in a rewards program. ARK users may optionally review the official Volcengine Collaboration Rewards Program. Quota, supported models, validity periods, and data-authorization terms can change. Check the official terms before opting in. Participation is not required to use Agent Web Search.

5. Brave

Variable	Required	Purpose
BRAVE_SEARCH_API_KEY	Yes	Brave Web Search API credential

Add brave to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

6. Gemini

Variable	Required	Purpose
GEMINI_API_KEY	Yes	Google AI API credential
AGENT_WEB_SEARCH_GEMINI_MODELS	No	Comma/newline-separated Gemini model IDs

Gemini maps common result and time controls into best-effort prompt constraints. One configured model stays fixed; multiple models are selected round-robin for successive requests.

7. Grok

Variable	Required	Purpose
XAI_API_KEY	Yes	xAI API credential
AGENT_WEB_SEARCH_GROK_MODELS	No	Comma/newline-separated Grok model IDs

One configured model stays fixed; multiple models are selected round-robin for successive requests.

When Grok is enabled, the public tool schema adds grok_search_mode:

• web_search searches the web.
• x_search searches X with native date filters when available.
• both exposes both server-side tools in one request and lets Grok choose; it does not issue two independent model requests.

8. Codex Alpha (experimental)

The codex_alpha provider uses only a gateway API key and a complete endpoint implementing /v1/alpha/search; it does not handle Codex OAuth tokens. Set the endpoint, key, and optional model, then add codex_alpha to AGENT_WEB_SEARCH_PROVIDERS:

Variable	Required	Purpose
AGENT_WEB_SEARCH_CODEX_ALPHA_ENDPOINT	Yes	Complete Alpha Search endpoint URL
AGENT_WEB_SEARCH_CODEX_ALPHA_API_KEY	Yes	Gateway Bearer API key
AGENT_WEB_SEARCH_CODEX_ALPHA_MODEL	No	Model ID, default gpt-5.6-luna

The provider sends a normal search_query command and returns standard web search results.

9. DeepSeek

DeepSeek uses the official Anthropic-compatible Messages API and the native web_search_20250305 server tool. It preserves the final model-generated text and maps only explicit web_search_result blocks into normalized results. A valid response may therefore have an answer with an empty results list.

Variable	Required	Purpose
DEEPSEEK_API_KEY	Yes	DeepSeek API credential
AGENT_WEB_SEARCH_DEEPSEEK_BASE_URL	No	Anthropic API base URL; defaults to https://api.deepseek.com/anthropic
AGENT_WEB_SEARCH_DEEPSEEK_MODELS	No	Comma/newline-separated model IDs; defaults to deepseek-v4-flash

Add deepseek to AGENT_WEB_SEARCH_PROVIDERS after providing the key. The provider appends /v1/messages to the configured base URL. Multiple models are selected round-robin for successive requests.

10. Perplexity

This provider uses Perplexity's native structured Search API. It returns result rows rather than a Sonar-generated prose answer; OpenRouter compatibility is intentionally outside this provider's scope.

Variable	Required	Purpose
PERPLEXITY_API_KEY	Yes	Perplexity Search API credential

Add perplexity to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

11. Tavily

Variable	Required	Purpose
TAVILY_API_KEY	Yes	Tavily Search API credential

Add tavily to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

12. You.com

You.com returns unified web and news sections. Agent Web Search merges both, deduplicates URLs, and applies max_results to the combined result list.

Variable	Required	Purpose
YDC_API_KEY	Yes	You.com Search API credential

Add you to AGENT_WEB_SEARCH_PROVIDERS after providing the key.

13. Zhipu Web Search

Zhipu Web Search uses the China standalone Web Search API and returns structured search rows. It is a separate Provider from Zhipu Chat Search; the implementation does not fall back between the two surfaces.

Variable	Required	Purpose
ZHIPU_WEB_SEARCH_API_KEY	Yes	Zhipu Web Search API credential
AGENT_WEB_SEARCH_ZHIPU_WEB_SEARCH_BASE_URL	No	China API base URL; defaults to https://open.bigmodel.cn

Add zhipu_web_search to AGENT_WEB_SEARCH_PROVIDERS after providing the key. The Provider appends /api/paas/v4/web_search to the configured base URL.

14. Zhipu Chat Search

Zhipu Chat Search uses the China GLM Chat Completions API with native web search. It returns the model answer plus only explicit top-level search rows; URLs mentioned in answer prose are not treated as citations. It is a separate Provider from Zhipu Web Search and has no API/Chat fallback.

Variable	Required	Purpose
ZHIPU_CHAT_SEARCH_API_KEY	Yes	Zhipu Chat Search API credential
AGENT_WEB_SEARCH_ZHIPU_CHAT_BASE_URL	No	China API base URL; defaults to https://open.bigmodel.cn
AGENT_WEB_SEARCH_ZHIPU_CHAT_MODELS	No	Comma/newline-separated GLM model IDs; defaults to glm-5.3-flash

Add zhipu_chat_search to AGENT_WEB_SEARCH_PROVIDERS after providing the key. The Provider appends /api/paas/v4/chat/completions to the configured base URL. Multiple configured models are selected round-robin for successive requests.

15. Responses

Responses is a generic OpenAI Responses API client for gateways that expose a server-side web search tool at POST {base_url}/responses. It traverses the output array (never assuming output[0] holds results), maps web_search_call action sources and url_citation annotations into normalized results, and preserves the model-generated answer. A response with only a message and no URLs keeps the answer, returns empty results, and marks searched as false.

Variable	Required	Purpose
AGENT_WEB_SEARCH_RESPONSES_BASE_URL	No	Base URL; defaults to https://api.openai.com/v1. Appends /responses, or /v1/responses when the base has no /v1 suffix
AGENT_WEB_SEARCH_RESPONSES_API_KEY	Yes	Bearer credential; falls back to OPENAI_API_KEY
AGENT_WEB_SEARCH_RESPONSES_MODELS	No	Comma/newline-separated model IDs; defaults to gpt-5-mini
AGENT_WEB_SEARCH_RESPONSES_TOOL_TYPE	No	Search tool type; defaults to web_search
AGENT_WEB_SEARCH_RESPONSES_TIMEOUT	No	Per-request timeout in seconds; overrides AGENT_WEB_SEARCH_TIMEOUT when set

Add responses to AGENT_WEB_SEARCH_PROVIDERS after providing the key. Multiple configured models are selected round-robin for successive requests.

16. Messages

Messages is a generic Anthropic Messages API client for gateways that expose a server-side web search tool at POST {base_url}/v1/messages. It traverses the content array (never assuming a single block holds results), maps web_search_tool_result / web_search_result blocks into normalized results, backfills missing titles from citations or the result domain, and preserves the model-generated answer. A response with only text and no URLs keeps the answer, returns empty results, and marks searched as false.

Variable	Required	Purpose
AGENT_WEB_SEARCH_MESSAGES_BASE_URL	No	Base URL; defaults to https://api.anthropic.com. Appends /v1/messages
AGENT_WEB_SEARCH_MESSAGES_ENDPOINT	No	Complete endpoint override; takes priority over the base URL
AGENT_WEB_SEARCH_MESSAGES_API_KEY	Yes	x-api-key credential
AGENT_WEB_SEARCH_MESSAGES_MODELS	No	Comma/newline-separated model IDs; defaults to claude-3-7-sonnet-20250219,claude-3-5-haiku-20241022
AGENT_WEB_SEARCH_MESSAGES_TOOL_TYPE	No	Search tool type; defaults to web_search_20250305
AGENT_WEB_SEARCH_MESSAGES_TOOL_NAME	No	Search tool name; defaults to web_search
AGENT_WEB_SEARCH_MESSAGES_TIMEOUT	No	Per-request timeout in seconds; overrides AGENT_WEB_SEARCH_TIMEOUT when set

Add messages to AGENT_WEB_SEARCH_PROVIDERS after providing the key. Multiple configured models are selected round-robin for successive requests.

Common search controls

Each provider maps the shared controls to its native API when possible and ignores unsupported controls.

Provider	max_results	time_range
DDGS	Native max_results	Native timelimit
Exa	Native result count	Native publish date
Parallel	REST: native max_results; keyless MCP: client-side truncation (results[:max_results])	Ignored
ARK	Native limit	Prompt constraint
Brave	Native count	Native freshness
Gemini	Prompt constraint	Prompt constraint
Grok	Prompt constraint	Prompt; X Search also uses native dates
Codex Alpha	Local result truncation	Ignored
DeepSeek	Local search-result truncation	Prompt constraint
Messages	Local deduplication and cap	Prompt constraint
Perplexity	Native max_results	Native recency filter
Tavily	Native max_results	Native time_range
You.com	Native count, combined cap	Native freshness
Zhipu Web Search	Native count, local deduplication and cap	Native recency filter
Zhipu Chat Search	Native count, local deduplication and cap	Native recency filter
Responses	Local deduplication and cap	Prompt constraint

Prompt-based controls are best-effort and are not strict guarantees.