DeepSeek Search API for Hermes Agent: Setup, Pricing and a Working Skill

What DeepSeek launched

On October 17, 2026, DeepSeek opened two web APIs to all API users, announced together with DeepSeek-V4.1-Flash-1017. Both run on DeepSeek's in-house search engine, which the company says serves hundreds of millions of requests a day.

The base URL is https://api.deepseek.com and authentication is the usual Authorization: Bearer header with a DeepSeek API key. Sources: the Search & Fetch guide and the pricing page.

What a search returns

A search takes a query of 1 to 128 characters and an optional count from 1 to 50 (default 10). Each result includes:

• title, url and date (publication time, or null)
• snippet, a 100–200 character summary for display
• summary, a 600–800 character summary written for a model to read
• content, the page text, only when you send need_content: true
• rerank_score from 0 to 3 (1.5 or above counts as high quality) and authority from 0 to 4 (-1 when unknown)

The query keeps search syntax: site:, -site:, "exact phrase", -term, lang:zh,en, after:2026-01-01 and before:. The ready-made summary field is the useful part for an agent: the model can answer from it without fetching every page.

curl https://api.deepseek.com/v1/tools/search \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "DeepSeek V4.1 Flash release", "count": 5}'

curl https://api.deepseek.com/v1/tools/fetch \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api-docs.deepseek.com/guides/search"}'

What it costs in practice

Billing is per successful request, not per token or per result. Empty searches, errors and timeouts are free, and asking for 50 results costs the same as asking for 5. A bot that runs 30 searches a day makes about 900 a month, which is roughly $0.68. If it also fetches two pages per search, add about $1.35.

The model tokens your agent spends reading those results are billed separately by whichever model provider you use. If you use DeepSeek through Claude Code, Codex or DeepSeek Harness, their built-in web search already calls this backend and becomes billable at 00:00 Beijing time on November 1, 2026 (16:00 UTC on October 31).

Does Hermes Agent support it?

Not natively yet. We checked the Hermes repository on October 17: neither main nor release v0.22.2 has a DeepSeek web backend. The built-in search backends are SearXNG, Tavily, Exa, Firecrawl, Parallel, Perplexity, Brave (free tier), DuckDuckGo, Keenable, xAI and OpenAI native search, chosen with web.search_backend in config.yaml.

Community work is in progress. Two third-party plugins that wrap the new endpoints have been submitted to the Hermes plugin catalog (#140154 and #140462), and #81393 proposes a backend built on DeepSeek's server-side search. All three were still open when we checked. Read a plugin's code before you give it your API key.

Until one lands, a skill is the simplest route. Hermes skills can declare the environment variables they need and run scripts through the terminal tool, so DeepSeek search becomes a tool your bot can choose.

Step 1: Create the skill

Hermes keeps skills in ~/.hermes/skills/<category>/<name>/. Save this as ~/.hermes/skills/research/deepseek-search/SKILL.md:

---
name: deepseek-search
description: Search the live web and read web pages through the DeepSeek Search & Fetch API.
version: 1.0.0
required_environment_variables:
  - name: DEEPSEEK_API_KEY
    prompt: DeepSeek API key
    help: Create one at https://platform.deepseek.com/api_keys
    required_for: web search and page fetch
metadata:
  hermes:
    tags: [search, web, deepseek]
    category: research
    requires_toolsets: [terminal]
---

# DeepSeek Search

## When to Use
The user asks about current events, prices, releases or anything that needs a live
web source, or asks you to read a specific URL.

## How to Use
Search. Each result has a title, URL, date and a summary written for a model:

    python3 "${HERMES_HOME:-$HOME/.hermes}/skills/research/deepseek-search/scripts/ds_search.py" search "query" 5

Read one page as Markdown:

    python3 "${HERMES_HOME:-$HOME/.hermes}/skills/research/deepseek-search/scripts/ds_search.py" fetch https://example.com/page

## Rules
- Keep a query under 128 characters. Operators work: site:, -site:, "exact phrase",
  lang:zh,en, after:2026-01-01, before:2026-06-01.
- Every successful call is billed to the key owner. Search once, then fetch only the
  pages you actually need.
- Cite the URLs you used.
- On HTTP 429 wait a second and retry once. On HTTP 402 tell the user the DeepSeek
  balance is empty.

The required_environment_variables block is what lets the script see your key: Hermes passes declared variables through to the terminal sandbox.

Step 2: Add the helper script

Save this as scripts/ds_search.py inside the same skill folder. It uses only the Python standard library.

#!/usr/bin/env python3
"""DeepSeek Search & Fetch for Hermes Agent.

  ds_search.py search "your query" [count]
  ds_search.py fetch https://example.com/page
"""
import json, os, sys, urllib.error, urllib.request

API = "https://api.deepseek.com/v1/tools/"


def call(endpoint, body):
    key = os.environ.get("DEEPSEEK_API_KEY")
    if not key:
        sys.exit("DEEPSEEK_API_KEY is not set")
    req = urllib.request.Request(
        API + endpoint,
        data=json.dumps(body).encode(),
        headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=60) as resp:
            return json.load(resp)
    except urllib.error.HTTPError as err:
        sys.exit(f"HTTP {err.code}: {err.read().decode(errors='replace')[:500]}")


if len(sys.argv) < 3 or sys.argv[1] not in ("search", "fetch"):
    sys.exit(__doc__)

if sys.argv[1] == "search":
    count = int(sys.argv[3]) if len(sys.argv) > 3 else 5
    data = call("search", {"query": sys.argv[2][:128], "count": count})
    if not data["results"]:
        print("No results.")
    for r in data["results"]:
        print(f"## {r['title']}\n{r['url']}  {r.get('date') or ''}\n{r['summary']}\n")
else:
    page = call("fetch", {"url": sys.argv[2]})
    print(f"Source: {sys.argv[2]}\n\n{page['content']}")

Step 3: Add your key and reload

Create a key in the DeepSeek platform (see our API key guide) and make sure the account has balance. Hermes reads secrets from ~/.hermes/.env:

H="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$H/skills/research/deepseek-search/scripts"

# Save the two files above as:
#   $H/skills/research/deepseek-search/SKILL.md
#   $H/skills/research/deepseek-search/scripts/ds_search.py

# Skip this line if DEEPSEEK_API_KEY is already in the file
echo 'DEEPSEEK_API_KEY=YOUR_OWN_DEEPSEEK_KEY' >> "$H/.env"

hermes skills list | grep deepseek-search
hermes gateway restart   # only if you talk to Hermes through Telegram, Discord or another app

Start a new conversation afterwards so the skill index is fresh. If you already use DeepSeek as your model provider, the same DEEPSEEK_API_KEY serves both.

Step 4: Test it

Run the script once by hand. This makes one billable search (a fraction of a cent):

H="${HERMES_HOME:-$HOME/.hermes}"
set -a; . "$H/.env"; set +a
python3 "$H/skills/research/deepseek-search/scripts/ds_search.py" search "DeepSeek V4.1 Flash release" 3

You should see titles, URLs and summaries. Then ask your bot something that needs current information, such as "What did DeepSeek release this week? Use the deepseek-search skill." Once it has used the skill successfully, you can drop the hint.

Error codes you might see: 401 means the key is wrong, 402 means the DeepSeek balance is empty, 429 means you passed five calls per second, and 404 from Fetch means the page had no readable content.

Should you switch from your current search backend?

The skill sits alongside the built-in web_search tool rather than replacing it. Keep your existing backend if it works for you: SearXNG is free and self-hosted, and paid backends such as Tavily or Exa are already wired into Hermes. DeepSeek search is worth trying if you want a low, flat per-call price, model-ready summaries in every result, or a second index to check answers against. Compare the options in our Hermes web search guide.

On OpenClaw Launch

Hermes bots on OpenClaw Launch already come with web search built in, with no per-query charge and no key to manage, so you do not need this API just to let your bot search. This guide is for self-hosted Hermes, and for developers who want DeepSeek's index specifically.

Frequently asked questions

Related guides

See DeepSeek V4.1 Flash for Hermes, Hermes with DeepSeek models, Hermes web search and Hermes hosting.

Deploy a Hermes agent with web search