> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Perplexity web search in Hermes
> Configure Hermes Agent to use Perplexity for web search and page extraction, verify the connection, and complete a source-grounded research workflow.
## 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](/docs/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 and use a separate Perplexity API key for search and extraction.
The 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
* A Hermes model provider configured for reasoning and writing
* A Perplexity API key
* Hermes `v0.21.1` (tag `v2026.9.7`) or later
Generate a key in the Perplexity API Console.
## Set up the integration
For a new command-line installation, run the installer for your platform:
```bash theme={null}
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc # Use ~/.zshrc if you use Zsh
```
```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.
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.
Open the tool setup wizard:
```bash theme={null}
hermes tools
```
Choose **Web Search & Extract**, select **Perplexity**, and enter your Perplexity API key when prompted. 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.
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.
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
Call the underlying Search API directly.
Review Search API request pricing before production use.
Learn about provider selection, caching, and fallback in Hermes.
Review the implementation and upstream validation.