Web research

The pi-web-agent extension adds a single research tool, web_explore, that searches, fetches, ranks sources, and escalates to a headless browser when a page needs it.

Bundled with Selesai

Loaded automatically with Selesai; no per-extension npm install is required.

Manifest entry

./pi-web-agent

Runtime surface

Mixed (commands, tools, shortcuts)

Setup and prerequisites

• This extension is bundled with Selesai. It is loaded automatically; you do not need to install it separately.
• With an active TokenIn account, default search uses TokenIn and falls back to DuckDuckGo. Otherwise it uses DuckDuckGo without credentials; when DuckDuckGo blocks a search (common on VPS and datacenter IPs), it falls back to Tavily’s keyless endpoint automatically — set PI_WEB_AGENT_DISABLE_KEYLESS_FALLBACK=1 to turn that off.
• Other key-based backends: SearXNG (self-hosted URL), Brave (webAgent.braveApiKey or PI_WEB_AGENT_BRAVE_API_KEY), You.com (YDC_API_KEY), Exa (EXA_API_KEY), and Tavily (TAVILY_API_KEY).
• Search fanout (optional): query several configured backends at once and rank pages that more than one provider agreed on to the top, via backends.search.fanout with off / on / auto modes (auto fans out only when the first provider returns thin results).
• Headless escalation uses the bundled local-browser provider. Make sure a Chromium-based browser (Chrome, Chromium, Edge, or Brave) is available on the system if you want headless page rendering.
• Direct readers: pasting a GitHub file/issue/PR, PDF, or YouTube URL reads the real content (raw source, extracted PDF text, or the transcript) keyless.

What it sets up

• Registers the /web-agent slash command to inspect and change presentation and backend settings.
• Registers the web_explore agent tool for bounded web research.
• Loads layered configuration from project and global pi-web-agent config files.
• Augments the system prompt on before_agent_start so the agent knows to use web_explore for web research instead of shell commands or direct HTTP calls.

What you can configure

Web research supports layered global/project backend and presentation config, API keys stored in settings.json, and runtime command controls.

Configuration locations and precedence

1. Global backend/presentation config
   ~/.selesai/agent/extensions/pi-web-agent/config.json
   Default lowest; overridden by project config.
2. Project backend/presentation config
   .selesai/extensions/pi-web-agent/config.json
   Overrides global config values.
3. User settings for secrets
   ~/.selesai/agent/settings.json
   Brave API key is read from webAgent.braveApiKey. Firecrawl key can live in config or env var.

Settings

Key / path	Type, default, and values	Description
presentation.defaultMode	string Default: "compact" Allowed values: "compact", "preview", "verbose"	Default presentation mode for web agent results.
presentation.tools.<web_search|web_fetch|web_fetch_headless|web_explore>.mode	string Default: — Allowed values: "compact", "preview", "verbose"	Per-tool presentation override.
backends.search.provider	string Default: "duckduckgo" Allowed values: "duckduckgo", "searxng", "brave"	Search backend provider.
backends.search.baseUrl	string Default: —	Base URL for searxng or brave endpoints when required.
backends.search.fallback	string Default: — Allowed values: "duckduckgo"	Only valid when provider is searxng or brave. Other values are rejected.
backends.search.options.categories	string[] Default: —	SearXNG categories. Must be non-empty when provided.
backends.search.options.language	string Default: —	SearXNG language. Must not be empty when provided.
backends.search.options.safesearch	number Default: — Allowed values: 0, 1, 2	SearXNG safe-search level.
backends.fetch.provider	string Default: "http" Allowed values: "http", "firecrawl"	Fetch backend provider.
backends.fetch.baseUrl	string Default: —	Firecrawl base URL (required for firecrawl provider).
backends.fetch.apiKey🔒	string Default: —	Firecrawl API key. Prefer PI_WEB_AGENT_FIRECRAWL_API_KEY env var.
backends.fetch.fallback	string Default: — Allowed values: "http"	Only valid when provider is firecrawl.
backends.fetch.options.formats	string[] Default: —	Firecrawl output formats. Must be non-empty when provided.
backends.fetch.options.onlyMainContent	boolean Default: —	Firecrawl main-content-only flag.
backends.headless.provider	string Default: "local-browser" Allowed values: "local-browser"	Headless escalation provider. The only supported value is local-browser.
webAgent.braveApiKey🔒	string Default: —	Brave Search API key stored in settings.json. Also accepts PI_WEB_AGENT_BRAVE_API_KEY env var.

Environment variables

Key / path	Description
PI_WEB_AGENT_BRAVE_API_KEY🔒	Override or supply the Brave API key without storing it in settings.json.
PI_WEB_AGENT_FIRECRAWL_API_KEY🔒	Override or supply the Firecrawl API key without storing it in config.json.

Command, tool, and shortcut controls

Key / path	Description
web_explore({ query: "..." })	Agent tool that runs search, fetch, and headless escalation.
/web-agent	Runtime command with settings, show, doctor, changelog, reset project, and reset global subcommands.

Source evidence

• src/extensions/pi-web-agent/src/presentation/types.ts
• src/extensions/pi-web-agent/src/presentation/config-store.ts
• src/extensions/pi-web-agent/src/backends/config.ts
• src/extensions/pi-web-agent/src/backends/settings-reader.ts
• src/extensions/pi-web-agent/src/backends/doctor.ts
• src/extensions/pi-web-agent/src/backends/factory.ts

What you can do

• Ask the agent to research a current topic:

What is the current recommended way to handle React Server Actions in Next.js 15?

Copy

• Refine a follow-up by calling web_explore again with a narrower query.
• Change presentation output to verbose when you need full page content, or compact when you want a short summary.

Commands, tools, and shortcuts

Command / tool	Description
web_explore({ query: "..." })	Research a web question with bounded search/fetch passes.
/web-agent [settings|show|doctor|changelog|reset project|reset global]	Manage presentation and backend configuration.

Limits and safety

• Output is generated from third-party sources; always verify critical facts against the original page.
• Headless escalation may fail if no supported browser is installed.
• SearXNG requires backends.search.baseUrl in config; Brave requires a valid API key from webAgent.braveApiKey (preferred) or PI_WEB_AGENT_BRAVE_API_KEY; You.com, Exa, and Tavily require YDC_API_KEY, EXA_API_KEY, and TAVILY_API_KEY respectively; Firecrawl requires backends.fetch.baseUrl and accepts backends.fetch.apiKey or PI_WEB_AGENT_FIRECRAWL_API_KEY.
• The extension instructs the agent not to use shell commands such as curl or direct HTTP URLs for web research; it must use web_explore.
• Presentation config files store only non-secret values. The Brave key can be stored per-user in ~/.selesai/agent/settings.json; use environment variables for CI or throwaway keys. The keyless Tavily fallback sends no key but is rate-limited; prefer a real provider key for heavy use.

Source evidence

Selesai version: 0.10.0

• Web agent source
• README mention