Web Search

Gives the agent a web_search tool. Simple mode returns titles, URLs, and snippets. Research mode (agentic_research=true) has a subagent search, open pages, and synthesize an answer.

Module: codumentor.plugins.websearch.

Users can turn the tool off for themselves in Settings → Extensions → Web Search.

Configuration

plugins:
  - module: codumentor.plugins.websearch
    class: WebSearchPlugin
    args:
      enabled: true
      provider: "duckduckgo"
      max_results: 10
      timeout: 30
      target_agents: "main"
      research_max_iterations: 15
      max_urls: 5
      max_chars_per_url: 30000
      max_content_length: 500000

Parameter	Default	Description
`enabled`	`true`	Enable the plugin.
`provider`	`"duckduckgo"`	`duckduckgo`, `brave`, `searxng`, `tavily`, `serper`, or `google_cse`.
`provider_config`	`{}`	Provider-specific keys (below).
`max_results`	`10`	Results per simple search.
`timeout`	`30`	Request timeout in seconds.
`research_max_iterations`	`15`	Cap on research-mode subagent steps. (`research_max_turns` is a deprecated alias.)
`max_urls`	`5`	URLs the research subagent may fetch per call.
`max_chars_per_url`	`30000`	Character cap per fetched page (research mode).
`max_content_length`	`500000`	Raw byte cap per fetched page (research mode).
`target_agents`	`"main"`	`"main"`, `"subagent"`, or `"all"`.

API keys in provider_config accept ${ENV_VAR} (process environment) or ${secret:<name>} (per-user, via User Secrets). Paid providers also read a well-known env var if api_key is omitted.

Providers

Provider	Required	Free tier (typical)
duckduckgo	none	Unlimited
brave	API key (`api_key` or `BRAVE_API_KEY`)	2000 queries/month
searxng	`base_url` of your instance	Unlimited (self-hosted)
tavily	API key (`api_key` or `TAVILY_API_KEY`)	Free tier
serper	API key (`api_key` or `SERPER_API_KEY`)	2500 free queries
google_cse	API key (`api_key` or `GOOGLE_API_KEY`) and CSE id (`cx` or `GOOGLE_CSE_ID`)	100/day

`provider_config` by provider

duckduckgo — no key.

provider: duckduckgo
provider_config:
  region: "wt-wt"         # search region; wt-wt = worldwide
  safesearch: "moderate"  # off | moderate | strict
  timelimit: null         # d | w | m | y

brave

provider: brave
provider_config:
  api_key: "${BRAVE_API_KEY}"   # or ${secret:brave_api_key}
  country: "us"
  search_lang: "en"
  safesearch: "moderate"

searxng — base_url is required.

provider: searxng
provider_config:
  base_url: "https://searx.example.com"
  categories: "general"
  language: "en"
  safesearch: 1            # 0=off, 1=moderate, 2=strict

tavily

provider: tavily
provider_config:
  api_key: "${TAVILY_API_KEY}"
  search_depth: "basic"    # or advanced
  include_answer: false
  include_domains: []
  exclude_domains: []

serper

provider: serper
provider_config:
  api_key: "${SERPER_API_KEY}"
  gl: "us"
  hl: "en"

google_cse

provider: google_cse
provider_config:
  api_key: "${GOOGLE_API_KEY}"
  cx: "${GOOGLE_CSE_ID}"
  gl: "us"
  lr: null                 # optional language restriction
  safe: "medium"

Tool: `web_search`

Argument	Required	Default	Description
`query`	yes	—	Search string, or a full research brief when `agentic_research` is true.
`agentic_research`	no	`false`	`true` to research across pages.
`num_results`	no	`max_results`	Simple mode only.

In research mode, write a detailed task rather than a short keyword query. Pair with Web Retrieve when you already have URLs.

Notes

Missing or invalid keys surface as a setup error from that provider.
Prefer simple mode for a quick lookup; research mode is slower by design.