Agent Web Search

AIエージェント向けマルチプロバイダーWeb検索。

Agent Web Searchは、Hermes、Codex CLI、Claude Code、OpenCode、および通常のスクリプトに、一貫したWeb検索ツールを提供します。独立したプロバイダーを並行して実行し、正規化された結果を返します。デフォルトのプロバイダーセットは以下のとおりです。

• ARK grounding — Volcengine ARK Responses API + web_search（Doubao）

• DDGS — DuckDuckGo検索

• Exa — Exa MCP検索（ベストエフォート。可用性はエンドポイントに依存します）

オプションのプロバイダーも実装されています。

• Gemini — Gemini Interactions APIによるGoogle検索グラウンディング

• Grok — ネイティブWeb検索とX Searchを備えたxAI Responses API

• Tavily — ネイティブの結果数・期間フィルターを備えたTavily Search API

アーキテクチャはプロバイダーベースのため、DeepSeek、Brave、その他の検索対応プロバイダーを、MCPやHermesのインターフェースを変更せずに追加できます。

クイックスタート

# 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

APIキーをシェル履歴、ソースコード、Gitコミット、スクリーンショットに置かないでください。ローカルの.env/シークレットマネージャーを使用し、プロセス環境で変数をエクスポートしてください。

Related MCP server: GroundRoute

Codex CLIから使用する

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

Claude Codeから使用する

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

または、プロジェクトの.mcp.jsonを追加します。

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

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
    }
  }
}

Hermesから使用する

GitHubからネイティブプラグインを直接インストールします。

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

このプラグインは標準のweb_searchツールを登録し、MCPやCLIで使用されるものと同じAgent Web Searchコアを呼び出します。汎用のMCPパスを希望する場合、Hermesはhermes mcp addで接続することもできます。

GitHubインストーラーは、パッケージとそのオプション依存関係をインストールします。

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

Hermesは、このプラグインが組み込みのweb_searchツールを意図的に置き換えるため、明示的な--allow-tool-override許可を必要とします。有効化後は新しいHermesセッションを開始してください。メッセージングチャネルを使用する場合は、ゲートウェイを再起動してください。

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コラボレーション報酬について

Agent Web Searchは、いかなる報酬プログラムへの参加も必須としません。ARKを使用することを選択したユーザーは、独自のAPIキーを作成し、任意で公式の**Volcengineコラボレーション報酬プログラム**を確認できます。このプログラムは現在のルールに応じて報酬リソースを提供する場合がありますが、割り当て量、サポート対象モデル、有効期間、データ承認条件は変更される可能性があります。オプトインする前に公式ページを確認してください。参加することは、プロバイダーのデータ承認条件を受け入れることを意味します。Agent Web Searchの使用には必須ではありません。

設定

• ARK_API_KEY: 任意。ARKプロバイダーが有効な場合のみ必要です。カンマ/改行区切りのキーを受け付けます。

• AGENT_WEB_SEARCH_PROVIDERS: 起動時に有効なプロバイダーセット。デフォルトはark,ddgs,exaです。

• AGENT_WEB_SEARCH_TIMEOUT: プロバイダーごとのタイムアウト（秒）。デフォルトは60です。

• AGENT_WEB_SEARCH_ARK_MODELS: カンマ区切りのARKモデルID。

• EXA_MCP_URL: 任意のExa MCPエンドポイント上書き。

• GEMINI_API_KEY: 任意のGeminiプロバイダーキー。

• AGENT_WEB_SEARCH_GEMINI_MODEL: 任意のGeminiモデルID。

• XAI_API_KEY: 任意のGrokプロバイダーキー。

• AGENT_WEB_SEARCH_GROK_MODEL: 任意のGrokモデルID。

• TAVILY_API_KEY: 任意のTavilyプロバイダーキー。

プロバイダーセットは、HermesプラグインまたはMCPサーバーの起動時に解決されます。公開web_searchスキーマはそのセットから生成されます。リクエストはprovidersでセットを絞り込むことはできますが、起動時に無効化されたプロバイダーを有効化することはできません。grokが起動時に有効な場合、スキーマはさらにgrok_search_modeを公開し、web_search、x_search、bothの値を受け付けます。bothは両方のxAIサーバーサイドツールを1つのリクエストで渡し、Grokにどちらを呼び出すかを判断させます。独立した2つのリクエストを送信するわけではありません。

共通の検索コントロール

公開インターフェースは、プロバイダーに依存しない1つのコントロールセットを維持します。各バックエンドは、可能な場合はそれらをネイティブAPIにマッピングし、サポートされていないコントロールは静かに無視します。

プロンプト制約はモデルベースのプロバイダーに対するベストエフォートであり、厳格な保証として提示されるものではありません。

設計原則

• 1つのコア、複数のアダプター。

• 失敗したプロバイダーが、成功したプロバイダーを破棄することはありません。

• プロバイダーの応答は、すべてのHTTP 200が成功した検索であるかのように装うのではなく、searched、error、modelでマークされます。

• テレメトリなし、共有APIキーサービスなし。

開発

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

ライセンス

MIT。