Perplexity web search in Hermes

Overview

Hermes Agent can use Perplexity as the backend for its web_search and web_extract tools. web_search returns ranked results from the Search API, 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. 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

Get a Perplexity API key

Generate a key in the Perplexity API Console.

Set up the integration

Install or update Hermes

For a new command-line installation, run the installer for your platform:

macOS / Linux / WSL
Windows (PowerShell)

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc  # Use ~/.zshrc if you use Zsh

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:

hermes update
hermes --version

See the Hermes installation guide and update guide for Docker, package-managed, and other installation methods. For a tag-pinned deployment, use v2026.9.7 or later.

Choose your model provider

Run the model setup wizard if Hermes cannot already complete a normal chat:

hermes model

Choose the provider and model that Hermes should use for reasoning and writing. This choice is independent of the Perplexity web backend.

Select Perplexity for web tools

Open the tool setup wizard:

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.

Configure manually

The wizard is the recommended path. To configure the integration manually, add the key to your existing ~/.hermes/.env:

PERPLEXITY_API_KEY=pplx-your-key-here

Merge these values into the existing web section of ~/.hermes/config.yaml:

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.

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:

hermes chat --toolsets web

Paste this smoke-test prompt:

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:

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:

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:

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

Search API quickstart

Call the underlying Search API directly.

Search API pricing

Review Search API request pricing before production use.

Hermes web tools

Learn about provider selection, caching, and fallback in Hermes.

Hermes integration source

Review the implementation and upstream validation.

Getting Started

Router API

Agent API

Search API

Search SDK

Embeddings API

Perplexity SDK

Admin & Management

Resources

Legacy API

Perplexity web search in Hermes

Overview

Prerequisites

Get a Perplexity API key

Set up the integration

Configure manually

Verify the connection

Tutorial: build a source-grounded decision brief

1. Find candidate sources

2. Extract evidence from a pinned page

3. Turn the evidence into a brief

How the tools behave

Troubleshooting

Next steps

Search API quickstart

Search API pricing

Hermes web tools

Hermes integration source

​Overview

​Prerequisites

Get a Perplexity API key

​Set up the integration

​Configure manually

​Verify the connection

​Tutorial: build a source-grounded decision brief

​1. Find candidate sources

​2. Extract evidence from a pinned page

​3. Turn the evidence into a brief

​How the tools behave

​Troubleshooting

​Next steps

Search API quickstart

Search API pricing

Hermes web tools

Hermes integration source

Overview

Prerequisites

Set up the integration

Configure manually

Verify the connection

Tutorial: build a source-grounded decision brief

1. Find candidate sources

2. Extract evidence from a pinned page

3. Turn the evidence into a brief

How the tools behave

Troubleshooting

Next steps