Agent Web Search

Multi-Anbieter-Websuche für KI-Agenten.

Agent Web Search bietet Hermes, Codex CLI, Claude Code, OpenCode und gewöhnlichen Skripten ein einheitliches Websuch-Tool. Es führt unabhängige Anbieter parallel aus und liefert normalisierte Ergebnisse. Der standardmäßige Anbieter-Set ist:

• ARK grounding — Volcengine ARK Responses API + web_search (Doubao)

• DDGS — DuckDuckGo-Suche

• Exa — Exa-MCP-Suche (Best Effort; Verfügbarkeit hängt vom Endpunkt ab)

Optionale Anbieter sind ebenfalls implementiert:

• Gemini — Google-Search-Grounding über Gemini Interactions API

• Grok — xAI Responses API mit nativer Websuche und X-Suche

• Tavily — Tavily Search API mit nativen Ergebnisanzahl- und Zeitraum-Filtern

Die Architektur ist anbieterbasiert, sodass DeepSeek, Brave und andere suchfähige Anbieter hinzugefügt werden können, ohne die MCP- oder Hermes-Schnittstellen zu ändern.

Schnellstart

# Omit this line when the ARK provider is not enabled.
export ARK_API_KEY="your_ark_api_key"
pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'
agent-web-search-mcp

Geben Sie API-Schlüssel nicht in die Shell-Historie, in Quellcode, Git-Commits oder Screenshots ein. Verwenden Sie einen lokalen .env-/Secret-Manager und exportieren Sie die Variable in der Prozessumgebung.

Related MCP server: GroundRoute

Verwendung mit Codex CLI

export ARK_API_KEY="your_ark_api_key"
codex mcp add agent-web-search -- \
  agent-web-search-mcp
codex mcp list

Verwendung mit Claude Code

export ARK_API_KEY="your_ark_api_key"
claude mcp add agent-web-search -- \
  agent-web-search-mcp

Oder fügen Sie eine Projekt-.mcp.json hinzu:

{
  "mcpServers": {
    "agent-web-search": {
      "command": "agent-web-search-mcp",
      "args": [],
      "env": {"ARK_API_KEY": "${ARK_API_KEY}"}
    }
  }
}

Verwendung mit OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-web-search": {
      "type": "local",
      "command": ["agent-web-search-mcp"],
      "environment": {"ARK_API_KEY": "${ARK_API_KEY}"},
      "enabled": true
    }
  }
}

Verwendung mit Hermes

Installieren Sie das native Plugin direkt von GitHub:

pip install 'ddgs>=9.0'
hermes plugins install JerryLiu369/agent-web-search --no-enable
hermes plugins enable agent-web-search --allow-tool-override

Das Plugin registriert das standardmäßige web_search-Tool und ruft denselben Agent-Web-Search-Kern auf, der von MCP und CLI verwendet wird. Wenn Sie den generischen MCP-Pfad bevorzugen, kann Hermes auch mit hermes mcp add verbunden werden.

Der GitHub-Installer installiert das Paket und seine optionalen Abhängigkeiten:

pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'

Hermes erfordert die explizite --allow-tool-override-Berechtigung, da dieses Plugin absichtlich sein integriertes web_search-Tool ersetzt. Starten Sie nach der Aktivierung eine neue Hermes-Sitzung; starten Sie das Gateway neu, wenn Sie einen Messaging-Kanal verwenden.

CLI

agent-web-search "What changed in the latest OpenAI Codex CLI?"
agent-web-search "GPU kernel generation papers from the past month" --time-range m --max-results 5
agent-web-search "latest news" --provider ark --provider ddgs

Volcengine-Kooperationsprämien

Agent Web Search erfordert keine Teilnahme an einem Prämienprogramm. Benutzer, die ARK verwenden möchten, können ihren eigenen API-Schlüssel erstellen und optional das offizielle Volcengine Collaboration Rewards Program prüfen. Das Programm kann gemäß seinen aktuellen Regeln Prämienressourcen bereitstellen, aber Kontingent, unterstützte Modelle, Gültigkeitsdauer und Datenautorisierungsbedingungen können sich ändern. Prüfen Sie die offizielle Seite, bevor Sie sich anmelden. Die Teilnahme bedeutet die Akzeptanz der Datenautorisierungsbedingungen des Anbieters; sie ist nicht erforderlich, um Agent Web Search zu verwenden.

Konfiguration

• ARK_API_KEY: optional; nur erforderlich, wenn der ARK-Anbieter aktiviert ist. Durch Komma/Zeilenumbruch getrennte Schlüssel werden akzeptiert.

• AGENT_WEB_SEARCH_PROVIDERS: beim Start aktiviertes Anbieter-Set; Standard ist ark,ddgs,exa.

• AGENT_WEB_SEARCH_TIMEOUT: Timeout pro Anbieter in Sekunden (Standard 60).

• AGENT_WEB_SEARCH_ARK_MODELS: durch Komma getrennte ARK-Modell-IDs.

• EXA_MCP_URL: optionale Exa-MCP-Endpunktüberschreibung.

• GEMINI_API_KEY: optionaler Gemini-Anbieterschlüssel.

• AGENT_WEB_SEARCH_GEMINI_MODEL: optionale Gemini-Modell-ID.

• XAI_API_KEY: optionaler Grok-Anbieterschlüssel.

• AGENT_WEB_SEARCH_GROK_MODEL: optionale Grok-Modell-ID.

• TAVILY_API_KEY: optionaler Tavily-Anbieterschlüssel.

Der Anbieter-Set wird beim Start des Hermes-Plugins oder MCP-Servers aufgelöst. Das öffentliche web_search-Schema wird aus diesem Set generiert. Eine Anfrage kann das Set mit providers eingrenzen, kann aber keinen Anbieter aktivieren, der beim Start deaktiviert wurde. Wenn grok beim Start aktiviert ist, stellt das Schema zusätzlich grok_search_mode mit den Werten web_search, x_search und both bereit. both übergibt beide xAI-Server-seitigen Tools in einer Anfrage und überlässt Grok die Entscheidung, welches aufgerufen wird; es sendet keine zwei unabhängigen Anfragen.

Allgemeine Suchsteuerungen

Die öffentliche Schnittstelle hält einen anbieterneutralen Satz von Steuerungen. Jedes Backend bildet sie nach Möglichkeit auf seine native API ab und ignoriert nicht unterstützte Steuerungen stillschweigend:

Prompt-Einschränkungen sind für modellgestützte Anbieter Best Effort; sie werden nicht als strikte Garantien dargestellt.

Designprinzipien

• Ein Kern, mehrere Adapter.

• Ein fehlgeschlagener Anbieter verwirft nicht erfolgreiche Anbieter.

• Anbieterantworten werden mit searched, error und model markiert, anstatt so zu tun, als wäre jede HTTP-200-Antwort eine erfolgreiche Suche.

• Keine Telemetrie und kein gemeinsamer API-Schlüsseldienst.

Entwicklung

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,ddgs,mcp]'
pytest -q
ruff check .

Lizenz

MIT.