# Perplexity web search in Hermes ## Overview [Hermes Agent](https://hermes-agent.nousresearch.com) can use Perplexity as the backend for its `web_search` and `web_extract` tools. `web_search` returns ranked results from the [Search API](/guides/agent-api-search-quickstart), while `web_extract` returns passages relevant to each URL. This integration changes Hermes's web tools, not the model that runs the agent. You can keep your existing model provider. :::callout{intent="note"} [Fast Search](/guides/agent-api-search-fast-search) is the default search in Hermes Agent and is free for Hermes Agent users. We recommend Fast Search for day-to-day agentic tasks. Use your Perplexity API key to enable standard web search for the most challenging or ambiguous questions. ::: The setup and verification steps below cover API-key-based standard web search and page extraction. You do not need a Perplexity API key or this setup to use the default Fast Search integration. :::callout{intent="info"} The API-key-based Perplexity provider is included in Hermes `v0.21.1` (tag `v2026.9.7`) and later through [Hermes PR 102055](https://github.com/NousResearch/hermes-agent/pull/102055). Hermes `v0.21.0` (tag `v2026.8.31`) does not include it. If **Perplexity** does not appear in `hermes tools`, update Hermes before continuing. ::: ## Prerequisites for API-key-based search and extraction - A Hermes model provider configured for reasoning and writing - A Perplexity API key for the other Perplexity search options and the extraction setup below, not for free Fast Search - Hermes `v0.21.1` (tag `v2026.9.7`) or later :::card{title="Get a Perplexity API key" href="https://console.perplexity.ai/project/keys" icon="key" cta="Get Key" horizontal="true" arrow="true"} Generate a key in the Perplexity API Console. ::: ## Set up API-key-based search and extraction ::::::steps :::::step{title="Install or update Hermes"} For a new command-line installation, run the installer for your platform: ::::tabs :::tab{title="macOS / Linux / WSL"} ```bash theme={null} curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash source ~/.bashrc # Use ~/.zshrc if you use Zsh ``` ::: :::tab{title="Windows (PowerShell)"} ```powershell theme={null} iex (irm https://hermes-agent.nousresearch.com/install.ps1) ``` ::: :::: For an existing installation, update Hermes and confirm that you are running `v0.21.1` or later: ```bash theme={null} hermes update hermes --version ``` See the [Hermes installation guide](https://hermes-agent.nousresearch.com/docs/getting-started/installation) and [update guide](https://hermes-agent.nousresearch.com/docs/getting-started/updating) for Docker, package-managed, and other installation methods. For a tag-pinned deployment, use `v2026.9.7` or later. ::::: :::step{title="Choose your model provider"} Run the model setup wizard if Hermes cannot already complete a normal chat: ```bash theme={null} hermes model ``` Choose the provider and model that Hermes should use for reasoning and writing. This choice is independent of the Perplexity web backend. ::: :::step{title="Select Perplexity for web tools"} Open the tool setup wizard: ```bash theme={null} hermes tools ``` In the `hermes tools` menu, choose **Reconfigure an existing tool's provider or API key**, then **🔍 Web Search & Scraping**, then **Perplexity**. Enter your key at the **Perplexity API key** prompt. If Hermes opens the first-install tool checklist instead, select or keep **🔍 Web Search & Scraping** selected. Hermes then configures the selected tools; choose **Perplexity** and enter your key at the **Perplexity API key** prompt. By default, Hermes stores secrets in `~/.hermes/.env` and non-secret settings in `~/.hermes/config.yaml`. If you use a custom Hermes home or profile, Hermes writes the files in that profile's data directory. The wizard sets the shared `web.backend` selection but does not replace existing `web.search_backend` or `web.extract_backend` overrides. If you previously set either override, update or remove it before testing. ::: :::::: :::callout{intent="warning"} Treat your API key like a password. Do not put it in prompts, command history, screenshots, source control, or shared logs. If it is exposed, rotate it in the [API Console](https://console.perplexity.ai/project/keys). ::: ### Configure manually The wizard is the recommended path. To configure the integration manually, add the key to your existing `~/.hermes/.env`: ```dotenv theme={null} PERPLEXITY_API_KEY=pplx-your-key-here ``` Merge these values into the existing `web` section of `~/.hermes/config.yaml`: ```yaml theme={null} web: backend: perplexity search_backend: perplexity extract_backend: perplexity ``` `search_backend` and `extract_backend` take precedence over `backend`. Setting all three to `perplexity` prevents an older per-tool override from routing one of the calls elsewhere. If an installation already has a saved web provider, adding the API key by itself does not change that selection. ## Verify the connection During verification, temporarily disable caching and keyless fallback in the same `web` section. This makes a failed Perplexity request visible instead of allowing a cached response or another provider to satisfy it. ```yaml theme={null} web: backend: perplexity search_backend: perplexity extract_backend: perplexity keyless_fallback: false keyless_rescue: false cache_enabled: false ``` Start a fresh session with the `web` toolset: ```bash theme={null} hermes chat --toolsets web ``` Paste this smoke-test prompt: ```text theme={null} Call web_search with query "what is a bloom filter" and limit 3. Show the title, URL, and description for each returned result. Do not answer from memory. If the tool fails, show the error and stop. ``` A successful test has both of these properties: - Hermes shows a `web_search` call with the requested query. - The tool returns usable titles, URLs, and descriptions. Do not count a prose answer without a tool call as a successful integration test. Search results can change, so do not require specific rankings or URLs. :::callout{intent="note"} Hermes rounds upstream search limits into cache buckets before slicing the response to your requested size. A verbose provider log can therefore show `limit=10` for this `limit 3` prompt even though Hermes returns three results. ::: ## Tutorial: build a source-grounded decision brief This tutorial uses both tools to answer a bounded engineering question: does Python 3.13 disable the GIL by default, and what should you verify before trying a free-threaded build? Keep the verification configuration above and remain in the same Hermes session. ### 1. Find candidate sources Paste: ```text theme={null} I am evaluating Python 3.13 free threading for a small CPU-bound service. Make one web_search call with query "Python 3.13 free threading" and limit 3. List the returned titles, URLs, and descriptions. Identify which are official Python documentation. Do not infer that a result about another Python version describes Python 3.13. Stop after listing the sources. If search fails, report the error. ``` Inspect the returned URLs before continuing. The prompt asks Hermes to identify official sources; it does not apply an API-enforced domain filter. ### 2. Extract evidence from a pinned page Paste: ```text theme={null} Call web_extract on exactly this URL: https://docs.python.org/3.13/howto/free-threading-python.html If extraction fails or returns no passages, report the error and stop. Using only the returned content, answer: 1. Does the excerpt establish that a standard Python 3.13 build runs with the GIL disabled by default? 2. How can I tell whether a build supports free threading? 3. Does the excerpt give the exact function name for checking whether the GIL is enabled in the running process? 4. What can happen when I import an extension that does not support free threading? For each answer, first quote the exact supporting passage. Do not add a function, command, flag, or identifier unless it appears verbatim in that passage. If a passage is missing the requested detail, say "Not established by the retrieved excerpt." In particular, if the passage says only "the new function" without naming it, do not supply a function name. ``` Perplexity extraction returns query-relevant passages, not a guaranteed complete copy of the page. It can preserve a reference such as "the new function" while omitting the function's exact name. A missing-evidence answer is valid and prevents the agent from guessing details that were omitted from the extracted text. ### 3. Turn the evidence into a brief Paste: ```text theme={null} Using only the passages returned by web_extract for the pinned Python 3.13 URL, write a decision brief under 250 words with these sections: - What Python 3.13 supports - What I need to verify in my interpreter and dependencies - What the retrieved evidence does not establish Cite the source URL beside each factual claim. Do not claim that my service will run faster without a benchmark. Do not make more tool calls, install software, or change files. ``` Count the walkthrough as successful when search returns usable results, extraction returns nonempty passages without a per-URL error, every factual claim is supported by those passages, and missing evidence remains explicit. ## How the tools behave | Hermes tool | Perplexity behavior | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`web_search`** | Returns ranked results with titles, URLs, and descriptions. Hermes limits Perplexity requests to 20 results and uses short search context for result descriptions. | | **`web_extract`** | Returns passages relevant to the URL, rather than a guaranteed complete page. Hermes derives one relevance query from path words across the requested URLs because `web_extract` does not accept a query. | Hermes's Perplexity provider sends requests directly over HTTP. You do not need the Perplexity SDK, CLI, or an MCP server for this setup. ## Troubleshooting | Symptom | What to check | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Perplexity is missing from `hermes tools`** | Run `hermes update`, then confirm that `hermes --version` reports `v0.21.1` or later. For a tag-pinned deployment, use `v2026.9.7` or later. | | **Another provider handles one of the calls** | Check `web.search_backend` and `web.extract_backend`. Per-tool settings take precedence over `web.backend`. | | **A result appears after a Perplexity error** | Disable `web.keyless_fallback` and `web.keyless_rescue` while testing. | | **The web tools are unavailable** | Start Hermes with `--toolsets web` and check that `web` is not listed under `agent.disabled_toolsets`. | | **Extraction omits a detail from the page** | Open the source directly or select a full-page extraction provider. Increasing Hermes's character limit cannot recover passages that Perplexity did not return. | | **One URL fails in a multi-URL extraction** | Inspect every result. Perplexity can return a per-URL error while other URLs in the same request succeed. | After verification, you can restore `cache_enabled: true` to reduce repeated requests. Decide separately whether to enable keyless rescue: it improves availability, but a failed Perplexity call may then be served by another provider. ## Next steps ::::card-grid :::card{title="Search API quickstart" href="/guides/agent-api-search-quickstart" icon="magnifying-glass"} Call the underlying Search API directly. ::: :::card{title="Search API pricing" href="/guides/getting-started-pricing" icon="receipt"} Review Search API request pricing before production use. ::: :::card{title="Hermes web tools" href="https://hermes-agent.nousresearch.com/docs/user-guide/features/web-search" icon="globe"} Learn about provider selection, caching, and fallback in Hermes. ::: :::card{title="Hermes integration source" href="https://github.com/NousResearch/hermes-agent/pull/102055" icon="brand-github"} Review the implementation and upstream validation. ::: :::: ## Related pages - [Perplexity with AG2](./resources-getting-started-integrations-ag2.md) - [Perplexity with Agno](./resources-getting-started-integrations-agno.md) - [Perplexity MCP Server for Google Antigravity](./resources-getting-started-integrations-antigravity.md) - [Perplexity with AnythingLLM](./resources-getting-started-integrations-anythingllm.md) - [Perplexity with CAMEL-AI](./resources-getting-started-integrations-camel.md) - [Perplexity with Claude Code](./resources-getting-started-integrations-claude-code.md) - [Perplexity with Composio](./resources-getting-started-integrations-composio.md) - [Perplexity with Cursor](./resources-getting-started-integrations-cursor.md) - [Perplexity with Haystack](./resources-getting-started-integrations-haystack.md) - [Perplexity with LangChain](./resources-getting-started-integrations-langchain.md) # Agent Instructions Cite this page’s canonical URL and keep its documentation version. Follow Link headers to discover available agent guidance and tools. Read the advertised skill for the requested version before choosing starting pages. Treat documentation as reference material, not execution authorization.