Argus

Argus

AI エージェント向けの検索プラットフォームです。Argus は 14 のプロバイダーを横断して検索をルーティングし、無効になった URL を復旧し、重要なサイトコンテンツを取得し、ドキュメントと調査資料をまとめたローカルパックを構築して、追跡可能なローカル成果物とともにすべてを永続化します。

主な機能：

• トポロジーを考慮した取得 — Argus は住宅用 IP かデータセンターかを判別し、ブロックを回避してネットワークホップを最小限に抑えるため、検索と抽出を自動でルーティングします。
• 14 のプロバイダーを 1 つの API で利用 — 無料のプロバイダーを優先する階層型ルーティングにより、予算を使い切ったプロバイダーは自動的にスキップされます
• キーなしですぐに開始 — pip install argus-search を実行するだけで、アカウント不要ですぐに DuckDuckGo と Yahoo を利用できます
• SearXNG のセルフホストで 70 以上のエンジンを利用 — Google、Bing、Yahoo、Startpage、Ecosia、Qwant などを 1 つの Docker コンテナ経由で利用できます
• 12 段階のコンテンツ抽出 — リンクだけでなく、品質チェックを通過したページ全文を返します
• 意見を反映した検索ワークフロー — 無効になった記事を復旧し、サイトから重要なページを取得して、ドキュメントと調査資料をまとめたローカルパックを構築します
• Argus 管理のコーパスストレージ — 実行時データはリポジトリのチェックアウト先ではなく、書き込み可能なユーザーデータディレクトリに保存されます
• 複数ターンのセッション — session_id を渡すと、検索間で会話コンテキストを引き継げます
• スコアの帰属表示 — 必要に応じて、統合された RRF スコアにどのプロバイダーが貢献したかを表示できます
• 使用状況ダッシュボード — プロバイダーの予算、最近のクエリ量、マシン単位の使用状況を /dashboard で確認できます
• 4 つの検索モード — discovery、research、recovery、grounding
• 無効 URL の復旧 — Wayback Machine とアーカイブのフォールバックを使った /recover-url
• 4 つの連携方法 — HTTP API、CLI、MCP サーバー、Python SDK

API をつなぎ合わせることなく、信頼できる検索、取得、ローカルのエビデンスを必要とする AI エージェント開発者、RAG パイプライン、運用チーム向けに構築されています。

ステータス：ベータ版です。検索ワークフローとコーパスモデルは本番運用を想定していますが、現在も成熟の途上にあります。

ステータスについては、公開されているステータスページをご覧ください。認証済みのメンテナーは、最新の日付入りレポートを確認するために、非公開のargus-ops READMEを利用できます。

現在の本番環境チェックポイント — 2026 年 9 月 7 日： 認証済みの HTTP API と MCP アダプターは稼働中で、サンプルとして確認した無料検索は SearXNG、Yahoo、GitHub 経由で動作します。DuckDuckGo は断続的に動作し、 取得ポリシーによってブロックされると、安全側に倒して失敗します。本番環境への 準備状況は ready=true, degraded です。機密情報を含まない認証情報のバージョンと アカウントスコープの紐付けが記録されるまで、有料プロバイダーは現在利用できません。 ブラウザー機能と復旧メタデータのエビデンスは引き続き未解決です。プロバイダーを 利用する前に、現在のステータスマトリクスをご確認ください。

目次

• クイックスタート
• 開発
• Argus がデータを書き込む場所
• 意見を反映したワークフロー
• プロバイダー
• HTTP API
• ダッシュボード
• 連携
  • CLI
  • MCP
  • Python
• コンテンツ抽出
• アーキテクチャ
• 設定
• Argus を使わない場合
• よくある質問

クイックスタート

モード 1：ローカル CLI（設定不要）

pip install argus-search && argus search -q "python web frameworks"

これだけです。検索は DuckDuckGo が処理するため、アカウントもキーもコンテナも必要ありません。今すぐノートパソコンから、無料で無制限に検索できます。ほかのプロバイダーを利用したくなったら、いつでも API キーを追加できます。追加しなくても構いません。

argus extract -u "https://example.com/article"       # extract clean text from any URL
argus recover-article -u "https://example.com/dead-post"
argus capture-site -u "https://docs.example.com"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Python 3.11 以降を搭載したあらゆるマシンで動作します。ノートパソコン、Mac Mini、Raspberry Pi、クラウド VM など、ホストするものは何もありません。

MCP（Claude Code、Codex、OpenCode、Cursor、VS Code）を利用する場合：

pipx install argus-search[mcp]
export ARGUS_MCP_STANDALONE=true  # explicit development-only local broker
argus mcp init --global --client all

これにより、Claude Code、Codex CLI、OpenCode、Cursor 用のネイティブ設定が書き込まれます。設定後、クライアントを再起動してください。stdio を手動で設定する場合：

{"mcpServers": {"argus": {"command": "argus", "args": ["mcp", "serve"], "env": {"ARGUS_MCP_STANDALONE": "true"}}}}

または、MCP Registry からインストールします：

{
  "mcpServers": {
    "argus": {
      "registryType": "pypi",
      "identifier": "argus-search",
      "runtimeHint": "uvx",
      "env": {"ARGUS_MCP_STANDALONE": "true"}
    }
  }
}

スタンドアロン開発ではサーバーもキーも必要ありませんが、明示的に有効にする必要があります。 本番環境の MCP は、常に認証済み HTTP オーソリティに処理を委任します。

正確な設定ファイル、確認コマンド、リモート HTTP の設定、トラブルシューティングについては、MCP クライアントの設定をご覧ください。

モード 2：フルスタックサーバー

Pi-hole を実行している Raspberry Pi や、デスクにある Mac Mini、古いノートパソコンをお持ちですか？それでフルスタックを実行できます。SearXNG（デフォルトでは無効の独自プライベート検索エンジン）と、ローカルで JS をレンダリングするコンテンツ抽出機能を利用できます。

# Optional: tell Argus it has residential egress to optimize routing
export ARGUS_EGRESS_TYPE=residential
ARGUS_SEARXNG_ENABLED=true docker compose up -d    # SearXNG + Argus

SearXNG は 512MB の RAM を使用し、誰にもレート制限、ブロック、課金されないプライベートな Google 風検索エンジンを提供します（デフォルトでは無効です。ARGUS_SEARXNG_ENABLED=true を設定してください）。すでに何百万人もの人が所有しているハードウェアで、Pi-hole と並行して実行できます。

Argus がデータを書き込む場所

Argus のコードと、Argus の実行時データは別のものです。

• コードは、Argus をインストールまたはクローンした場所に保存されます。
• 実行時のコーパスデータは、platformdirs が解決する書き込み可能なユーザーデータディレクトリか、ARGUS_DATA_ROOT を設定して上書きした場合はその場所に保存されます。

お使いのマシン上の正確なパスを確認します：

argus paths

デフォルトでは、Argus は以下の場所に書き込みます：

• 公式ドキュメントのキャッシュは、解決された docs/cache/ の下
• リサーチパックは docs/research/ の下
• ワークフローの実行状態は workflows/runs/ の下
• バージョン管理されたワークフローのスナップショットは snapshots/ の下

つまり、Argus には兄弟ディレクトリの ../docs-cache チェックアウトは必要ありません。古い docs-cache ツリーがある場合は、次のコマンドで一度インポートしてください：

argus corpus import-docs-cache -s /path/to/docs-cache

独自のワークフロー

これらのワークフローは、一時的な JSON レスポンスだけでなく、ローカルの成果物を作成します。

消えた記事を復元する

argus recover-article -u "https://example.com/old-post" -t "Example Post"

Argus は復元候補を検索し、最適な結果を抽出して、復元したソースをローカルに保存します。さらに、引用元に基づくレポートとマニフェストを書き込みます。

サイトの重要な部分を保存する

argus capture-site -u "https://docs.example.com"

Argus は同一ドメイン内にとどまり、サイトマップを使った検出とヒューリスティックなリンクスコアリングを組み合わせて、見つかった重要なページを保存し、参照情報を含む詳細な要約を書き込みます。

ドキュメント + リサーチパックを作成する

argus build-research-pack -t "example sdk"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Argus は公式ドキュメントをローカルのドキュメントキャッシュに取り込み、検索から見つかった公式以外の補足ソースを追加して、追跡可能な成果物を含む統合リサーチパックを書き込みます。

開発

リポジトリの開発環境は Python 3.12 に固定されています。パッケージの実行に必要な Python の最低バージョンは 3.11、本番環境のイメージは Python 3.12.3 を実行し、Python 3.13 は互換性 CI の対象です。必須の CI はこの 3 つすべてに合格する必要があります。ローカルでの検証を正式な環境に合わせ、古いシステムインタープリターを誤って使わないよう、コントリビューターは以下の uv ワークフローを使用してください。

uv sync --python 3.12 --extra dev --extra mcp
uv run pytest tests/ -v --tb=short

リポジトリには 3.12 を指定した .python-version が含まれているため、uv、pyenv などのツールはデフォルトで適切なインタープリターを選択します。コントリビューター向けの詳しいガイダンスは、CONTRIBUTING.md をご覧ください。

プロバイダー

¹ SearXNG は Google、Bing、Yahoo、Startpage、Ecosia、Qwant、Wikipedia など 60 以上の検索エンジンを集約し、単一のセルフホスト型エンドポイントから利用できます。空き RAM が 512MB あるマシンで docker compose up -d を実行してください。

² WolframAlpha が返すのはウェブ検索結果ではなく、計算結果（数学、単位変換、事実の検索）です。grounding モードと research モードでのみ有効になります。計算できないクエリ（一般的なウェブ検索）には空の結果を返し、エラーもヘルス評価への影響もありません。

API キーを使う毎月付与の無料枠プロバイダーからは、月 7,000 回以上の無料クエリを利用できます（WolframAlpha 2k + Brave 2k + Tavily 1k + Exa 1k + Linkup 1k）。また、カード登録済みの対象アカウントで Parallel の月次クレジットが利用可能な場合は、最大 12,000 回以上となります。DuckDuckGo、Yahoo、GitHub には月間上限がありません。SearXNG はデフォルトで無効です（.env で有効にしてください）。ルーティングの優先順位は、Tier 0（無料：SearXNG*、DuckDuckGo、Yahoo、GitHub、WolframAlpha）→ Tier 1（毎月付与：Brave、Tavily、Exa、Linkup、Parallel）→ Tier 3（登録時に一度だけ付与：Serper、You.com、Valyu、SearchAPI）です。予算を使い切ったプロバイダーは自動的にスキップされます。

これらはパッケージレベルのプロバイダー階層と公称割り当て量であり、 本番環境で現在利用可能であることを保証するものではありません。本番環境の 権限管理では、登録時のフィンガープリント、アカウントのスコープ、 予算、承認済みテストのエビデンスがそろうまで、認証情報が設定された プロバイダーをフェイルクローズします。保護されたキー値があるだけでは、 現在のキーが機能する証明にはなりません。現在の分類については docs/STATUS.md を参照してください。

HTTP API

すべてのエンドポイントには /api が付きます。OpenAPI ドキュメントは http://localhost:8000/docs にあります。

ローカルのループバック呼び出しでは、認証なしで API を利用できます。リモート HTTP クライアントは ARGUS_API_KEY を Authorization: Bearer ... または X-API-Key: ... のいずれかで送信する必要があります。/api/admin/* 配下の特権ルートでは ARGUS_ADMIN_API_KEY が必要です（管理者用の個別キーが設定されていない場合は ARGUS_API_KEY にフォールバックします）。

# Search
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "mode": "discovery", "max_results": 5}'

# Search with score attribution
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "include_attribution": true}'

# Multi-turn search (conversational refinement)
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what about async?", "session_id": "my-session"}'

# Extract content from a working URL
curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

# Recover a dead or moved URL
curl -X POST http://localhost:8000/api/recover-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/old-page", "title": "Example Article"}'

# Network-free process liveness (container health target)
curl http://localhost:8000/api/live

# Public minimal startup and cached readiness
curl http://localhost:8000/api/startup
curl http://localhost:8000/api/ready

# Authenticated operator status, health compatibility, and budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/dead-letters
# After correcting the cause of a permanent rejection:
curl -X POST -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/DELIVERY_ID/recover

/api/health は、互換性のための HTTP 200 を返す稼働状態確認ルートです。意図的に PostgreSQL、プロバイダー、Maya、ブラウザーをチェックしないため、依存先の 障害によってコンテナーの再起動が連続することはありません。標準的なトポロジーと 運用手順については本番運用を、エンドポイントのセマンティクス、 準備状態の分類、観測情報の有効期限、安全なテレメトリーについては 運用ステータスを参照してください。

検索モード

ティアに基づくルーティングが常に最初に適用されます。各ティア内では、モードによってプロバイダーの順序が選択されます。

応答形式

{
  "query": "python web frameworks",
  "mode": "discovery",
  "results": [
    {
      "url": "https://fastapi.tiangolo.com",
      "title": "FastAPI",
      "snippet": "Modern Python web framework",
      "provider": "duckduckgo",
      "score": 0.0164,
      "score_attribution": {"duckduckgo": 0.0164},
      "egress": "unknown",
      "machine": null
    }
  ],
  "total_results": 1,
  "cached": false,
  "traces": [
    {"provider": "duckduckgo", "status": "success", "results_count": 5, "latency_ms": 312}
  ]
}

各結果には url、title、snippet、domain、provider、score が含まれます。traces 配列には、呼び出されたプロバイダーとその結果が示されます。

include_attribution が true の場合、各結果には 結果の Reciprocal Rank Fusion スコアを分解したプロバイダーごとのスコアマップである score_attribution も含まれます。RRF は加算式のため、各プロバイダーの寄与値は そのプロバイダー自身の順位による寄与と一致し、その値の合計は score になります。アトリビューションは既定で無効であり、アトリビューションなしの検索とは別にキャッシュされます。

予算

{
  "budgets": {
    "brave": {"remaining": 1847, "monthly_usage": 153, "usage_count": 153, "exhausted": false},
    "duckduckgo": {"remaining": 0, "monthly_usage": 0, "usage_count": 42, "exhausted": false}
  },
  "token_balances": {"jina": 9833638}
}

各プロバイダーは使用量を追跡します。ティア 1（月次）では 30 日間のローリングウィンドウを使用し、ティア 3（1 回限り）ではリセットされない生涯カウンターを使用します。プロバイダーが予算に達すると、Argus はそのプロバイダーをスキップして次に進みます。無料プロバイダー（DuckDuckGo、GitHub）には上限がありません。SearXNG は無料ですが、既定では無効になっています。プロバイダーごとにカスタム上限を適用するには、ARGUS_*_MONTHLY_BUDGET_USD を設定します。

ダッシュボード

HTTP サーバーを実行し、/dashboard を開きます。

argus serve
# http://127.0.0.1:8000/dashboard

ダッシュボードには、プロバイダー予算の消費状況、予算ペースを超過しているプロバイダーと使い切ったプロバイダー、 過去 30 日間のクエリ量、マシンごとの使用状況、最近のプロバイダーの アクティビティが表示されます。予算カードは自動的に更新されます。

ダッシュボードへのログインを必須にするには、ARGUS_ADMIN_API_KEY を設定します。管理者キーが設定されていない場合、 サーバーにアクセスできる人なら誰でもダッシュボードを利用できるため、信頼できるローカル環境での使用にのみ適しています。

リバースプロキシの背後でサブパスにデプロイする場合は、外部パスのプレフィックスを ARGUS_ROOT_PATH に設定します。

ARGUS_ROOT_PATH=/argus argus serve

これにより、プロキシが Argus を https://khamel.com/argus/ のようなパスで提供する場合でも、ダッシュボードのリダイレクト、リンク、HTMX フラグメント URL が機能します。

HTTPS で直接公開する場合、リポジトリには Caddy プロファイルが含まれています。

ARGUS_DOMAIN=argus.example.com [email protected] \
  docker compose --profile proxy up -d

既存の Authentik/nginx デプロイでは、プロキシ層で認証を維持し、ARGUS_ROOT_PATH を公開プレフィックスに設定します。

統合

CLI

argus search -q "python web framework"              # zero-config, uses DuckDuckGo
argus search -q "python web framework" --mode research -n 20
argus search -q "python web framework" --free        # free providers only (no paid API calls)
argus search -q "python web framework" --attribution # show per-provider score attribution
argus search -q "fastapi" --session my-session       # multi-turn context
argus extract -u "https://example.com/article"       # extract clean text
argus extract -u "https://example.com/article" -d nytimes.com  # auth extraction
argus recover-url -u "https://dead.link" -t "Title"
argus doctor                                         # full setup diagnostics
argus health                                         # provider status
argus budgets                                        # budget + token balances
argus mcp check                                      # validate MCP setup
argus set-balance -s jina -b 9833638                 # track token balance
argus test-provider -p brave                         # smoke-test a provider
argus serve                                          # start API server
argus mcp serve                                      # start MCP server
argus mcp init                                       # add MCP config to project

すべてのコマンドで、構造化出力用の --json を使用できます。

argus ledger reconcile-sessions \
  --source sqlite:///argus_budgets.db \
  --target "$ARGUS_DB_URL"
# Review source/imported/skipped/conflicting, then repeat with --apply.

MCP は、認証済み HTTP API 上のステートレスな実行アダプターです。プロバイダーやブローカーを構築せず、ブラウザー、データベース、予算、セッション、ヘルス、アウトボックスの状態も管理しません。アダプタープロセスは次のように設定します。

export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN=replace-with-a-scoped-caller-token

デプロイ済みの本番エンドポイントは、検証済みの MCP 2025-11-25 互換性コントラクトと、MCP 2026-07-28 ステートレストランスポート改訂版の両方に対応しています。 新しい方式はワンショットで、初期化ハンドシェイクや Mcp-Session-Id は不要です。永続的なポリシー、予算、セッション、エビデンスは引き続き HTTP オーソリティが管理します。境界の根拠と必須の無支出プローブについては、 docs/research/2026-08-11-mcp-stateless-production-authority.md を参照してください。

オプション A — ローカルアダプター（stdio）

MCP クライアントと同じマシンにアダプターをインストールします。

{
  "mcpServers": {
    "argus": {
      "command": "argus",
      "args": ["mcp", "serve"]
    }
  }
}

argus が PATH にない場合は、フルパスを使用してください："/home/you/.local/bin/argus"。 アダプターはクライアントプロセスから ARGUS_AUTHORITY_URL と ARGUS_AUTHORITY_TOKEN を継承します。代わりにローカルブローカーを実行するには、開発環境で ARGUS_MCP_STANDALONE=true を明示的に設定する必要があります。本番環境では拒否されます。

Claude Code、Codex CLI、OpenCode、Cursor、および stdio ベースのあらゆる MCP クライアントで動作します。argus mcp init --global --client all を使うと、現在のマシン用に各クライアントのネイティブ設定を書き込めます。

クライアントの詳細なセットアップ手順と確認コマンドは、docs/mcp-clients.md にあります。

オプション B — リモート MCP アダプター（Tailscale 経由のクライアント）

Argus を 1 台のマシンで実行し、各クライアントをネットワーク経由で接続します。クライアントへのローカルインストールは不要です。

アダプターのホストで：

export ARGUS_API_KEY=replace-with-a-long-random-secret
export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN="$ARGUS_API_KEY"
argus mcp serve --transport streamable-http --host YOUR_TAILSCALE_IP --port 8001

リモート MCP の認証情報は、HTTP オーソリティ上でも有効なスコープ付き認証情報である必要があります。アダプターは認証済みの各ベアラートークンを変更せずに転送するためです。stdio の場合、ARGUS_AUTHORITY_TOKEN は呼び出し元の認証情報です。

systemd ホストで HTTP API とリモート MCP サービスを再起動後も実行し続けるには：

cat >mcp.env <<'EOF'
ARGUS_AUTHORITY_URL=http://argus-api:8000
ARGUS_AUTHORITY_TOKEN=replace-with-scoped-caller-token
ARGUS_API_KEY=replace-with-the-same-scoped-caller-token
EOF
chmod 600 mcp.env
ARGUS_MCP_ENV_FILE="$PWD/mcp.env" scripts/install-systemd.sh
systemctl status argus argus-mcp --no-pager

インストーラーは最小限のアダプター環境を検証し、root のみがアクセスできる /etc/argus/mcp.env としてインストールした後、両方のユニットをインストールして起動します。MCP ユニットは、オーソリティの .env、プロバイダーのボールト、データベース設定、ブラウザーのパス、書き込み可能なデータボリュームを読み込みません。

各クライアントで：

Tailscale を使う場合、<server> はマシンの Tailscale IP（例：100.x.x.x）です。サーバー 1 台で、メッシュ内のすべてのマシンから検索できます。

ワンコマンドでのプロビジョニング：

# Load secrets, then push config to any machine:
eval $(secrets decrypt argus | grep -E 'ARGUS_REMOTE_URL|ARGUS_API_KEY' | sed 's/^/export /')

curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s local              # this machine; uses local stdio if argus is installed
curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s [email protected]    # remote machine

スクリプトは対象環境に Claude/Cursor、Codex、OpenCode の設定を書き込みます。 ローカル stdio では MCP リスナーキーは不要ですが、アダプターには引き続き スコープ付きの ARGUS_AUTHORITY_TOKEN が必要です。リモート MCP モードでは ARGUS_REMOTE_URL と ARGUS_API_KEY が必要です。Python 3 が必要です。

argus mcp init でも設定を自動生成できます：

argus mcp init --global              # local stdio adapter for Claude Code + OpenCode + Cursor
argus mcp init --client codex        # local stdio for Codex (writes ~/.codex/config.toml)
argus mcp init --client opencode     # local stdio for OpenCode
ARGUS_REMOTE_URL=http://argus.local:8271 ARGUS_API_KEY=... argus mcp init --global --client all
argus mcp init --client gemini       # prints gemini mcp add command
argus mcp init --global --client all # everything above

リリース状況

main にプッシュしても PyPI には公開されません。パッケージと MCP Registry の公開は、リリース作成時または手動ディスパッチ時に GitHub の公開ワークフローを通じて行われます。バージョンの同期、公開前チェック、公開の検証については、docs/releasing.md を参照してください。

トランスポート：stdio（デフォルトのローカルアダプター）、sse（レガシーのリモート）、streamable-http（最新のリモート、設定では"type":"http"）。リモート MCP トランスポートには ARGUS_API_KEY が必要です。すべてのトランスポートは実行を ARGUS_AUTHORITY_URL に委譲します。

利用可能なツール：

• HTTP を利用する stdio およびリモート MCP：search_web、extract_content、 recover_url、expand_links、search_health、search_budgets、 recover_dead_article、capture_site、build_research_pack
• 明示的なスタンドアロン開発では、ローカル専用の test_provider、cookie_health、valyu_answer、パス／ファイルツール、 リソースも利用できます。これらは意図的に本番用アダプターには含まれていません。

search_web では、free_only=true を指定すると無料（tier-0）のプロバイダーのみに結果を絞り込めます。また、include_attribution=true を指定すると、Markdown レスポンスにプロバイダーごとのスコアの内訳が含まれます。

MCP と HTTP で Argus を使用する

トランスポートは 2 種類ですが、ルールは 1 つです。エージェントは MCP を、それ以外はすべて HTTP を使用します。

• MCP（argus mcp serve）— MCP にネイティブ対応した AI ハーネス向けの、ステートレスで認証済みのアダプターです。コアツールは HTTP オーソリティに処理を委譲します： search_web、extract_content、recover_url、expand_links、ワークフローの開始。MCP を再起動しても、会計、セッション、ヘルス、アウトボックスの状態が分岐することはありません。
• HTTP（POST /api/search、POST /api/extract、 POST /api/workflows/...）— スクリプト、cron ジョブ、サービス連携（Maya を含む）向けです。スコープ付きの呼び出し元認証情報を Authorization に指定してください。本文の "caller" 値は診断用ラベルであり、認証済みの ID を上書きすることはできません。

より広範なサービス群（Maya / Hermes / Argus）におけるサービス間トランスポートとロールの契約は、Maya のアーキテクチャドキュメントを正とします。

Python

ブローカーと抽出機能を直接インポートする方法は、スタンドアロン開発向けの利便性を目的としています。本番環境の Python 呼び出し元は、すべての実行と永続的な会計を単一のオーソリティに集約するため、認証済み HTTP API を使用します。

from argus.broker.router import create_broker
from argus.models import SearchQuery, SearchMode
from argus.extraction import extract_url

broker = create_broker()

response = await broker.search(
    SearchQuery(query="python web frameworks", mode=SearchMode.DISCOVERY, max_results=10),
    compute_attribution=True,
)
for r in response.results:
    print(f"{r.title}: {r.url} (score: {r.score:.3f})")
    print(r.score_attribution)

content = await extract_url(response.results[0].url)
print(content.title)
print(content.text)

コンテンツの抽出

Argus は、あらゆる URL からコンテンツを抽出するため、最大 12 種類の方法を試します。まず有料記事向けの認証抽出を行い、次にローカル抽出ツール（trafilatura、Crawl4AI、Obscura、Playwright、住宅用 IP）、続いて外部 API（Jina、Valyu Contents、Firecrawl、You.com、Wayback、archive.is）を試します。各試行では、完全性と不要な出力がないかを品質チェックします。抽出ツールの詳細な比較については、docs/providers.md を参照してください。

完全性の評価は、抽出が成功するたびに自動的に実行されます。Argus は、末尾の省略記号、フィードの切り捨てマーカー（「続きを読む」、WordPress RSS のフッターなど）、文の途中での終わり方、不自然に途切れた最終段落、不審に丸められた単語数という 5 つの指標を採点し、テキストとともに is_complete、completeness_confidence、truncation_type を返します。信頼度が 85％以上の場合、Argus は部分的な結果を返さずに次の抽出ツールを試し続けます。そのため、たとえば trafilatura による取得結果が「...」で終わる場合は、Playwright、Jina、Wayback などへ自動的にフォールバックします。すでにテキストを持っている呼び出し元（RSS フィードの項目など）は、抽出を実行せずに完全性をチェックするため、POST /api/assess-content を利用できます。

Obscura（オプション）は、ステルスモードを内蔵した軽量な Rust 製ヘッドレスブラウザーです（バイナリは約 70MB、RAM は 30MB）。navigator.webdriver=undefined に設定し、セッションごとに Canvas／GPU／オーディオのフィンガープリントをランダム化して、3,520 のトラッカードメインをブロックします。これにより、通常の Playwright／Chrome をブロックする、JavaScript を多用するサイトやスクレイピング対策サイトでのボット検出に直接対処できます。API キーもレート制限も不要で、すべてローカルで動作します。

使用方法は 2 通りあります。

バイナリをインストールします：github.com/h4ckf0r0day/obscura/releases

Extract は、有効な URL の全文を取得し、そのテキストが完全かどうかを知らせます。Recover-URL は、URL が無効になっている、有料記事になっている、または大幅に変更されている場合に、代替 URL を見つけます。

アーキテクチャ

Caller (CLI/HTTP/MCP/Python) → SearchBroker → tier-sorted providers → RRF ranking → response
                                     ↕ SessionStore (optional)
                            Extractor (on demand) → 12-step fallback chain with quality gates

新しいプロバイダーや抽出ツールは、アダプターファイルを 1 つ追加するだけで導入できます。インターフェースについては、CONTRIBUTING.md を参照してください。

クエリの処理方法

query arrives → cache? → build provider queue → execute sequentially → RRF fuse → dedup → respond

1. キャッシュの確認。 SearchCache は正規化されたクエリ、モード、帰属情報が要求されているかどうかをハッシュ化します（SHA256）。キャッシュにヒットすると、TTL 168 時間（7 日）で直ちに結果を返します。

2. プロバイダーキュー。 resolve_routing() はモード固有の優先リストを取得し、ティア順に安定ソートします。ティア 0（無料）が先、ティア 1（月額）が次、ティア 3（買い切り）が最後です。検索モードの例：

   searxng → duckduckgo → yahoo → github → brave → exa → tavily → linkup → parallel → serper → you → valyu
   

3. ゲートを通過しながら順次実行。 各プロバイダーを順番に確認します。API 呼び出しの前に、次の 4 つのゲートをすべて通過する必要があります。

   • 設定 — プロバイダーが有効で、設定済み（API キーが存在する）ですか？
   • ヘルス — 5 回以上連続で失敗していませんか（60 分間のクールダウンが開始されます）？
   • 予算 — ティア 1 以上の場合、予算を使い切っていませんか？ ティア 1（月額）では、7 日間の使用率で残りの予算が 1 週間未満で尽きるかを確認します。使用量の少ない日は余裕として蓄積されます。ティア 3（買い切り）では、生涯カウンターでアクセスを制限し、予算の使い切りのみを確認します。
   • 実行 — 実際の HTTP 呼び出しです。成功すると失敗カウンターがリセットされ、失敗すると増加します。

4. RRF による統合。 各プロバイダーからの結果を、Reciprocal Rank Fusion（k=60）を使用して統合します。各結果のスコアは、その結果を返したすべてのプロバイダーにおける 1/(k + rank) の合計です。複数のプロバイダーに表示された結果ほど上位にランク付けされます。

5. 重複排除と切り詰め。 URL を正規化（www.、utm_* などのトラッキングパラメーター、末尾のスラッシュを削除）して重複を排除します。統合したリストは max_results（デフォルトは 10）件に切り詰められます。

6. キャッシュと永続化。 authority は最終レスポンスをメモリー内キャッシュと、設定済みの SQL リポジトリー（本番環境では PostgreSQL、スタンドアロン開発では SQLite）に書き込みます。検索結果と抽出結果には、後続の監査に使用する来歴メタデータ（egress、machine、source_type）が含まれます。既存のデータベースは起動時に追加的な変更によってアップグレードされます。

設定

すべての設定は環境変数で行います。一覧は .env.example を参照してください。API キーが必要なプロバイダーは、オプトイン方式です。API キーと ARGUS_<PROVIDER>_ENABLED=true の両方を設定してください。キーが不足している場合は適切に処理され、エラーではなくプロバイダーがスキップされます。

リポジトリーから実行する場合、Argus は .env と .env.local を自動で読み込みます（すでにエクスポートされている環境変数は上書きしません）。この動作を無効にするには、ARGUS_AUTOLOAD_DOTENV=false を設定してください。

Argus を使用すべきでないケース

検索、キャプチャ、来歴、ローカルアーティファクトをまとめて利用したい場合に、Argus が最適です。

次の場合は、Argus の使用を避けてください。

• 代替手段や予算管理は不要で、検索 API が 1 つだけ必要な場合
• 永続的なコーパスやレポート出力は不要で、単発のページスクレイピングだけが必要な場合
• バックエンドの検索インフラではなく、エンドユーザー向けの検索 UI が必要な場合
• ヒューリスティックや LLM を利用した処理を使わず、完全に決定論的な要約が必要な場合

よくある質問

Tavily／Serper を直接呼び出すのとは何が違いますか？ Argus が代わりに呼び出します。さらに 13 のプロバイダーも利用できます。複数の API キーを管理して結果をつなぎ合わせる代わりに、ランキングされ、重複が除去された 1 つの結果セットを取得できます。無料のプロバイダーが先に試されるため、必要な場合にだけクレジットが消費されます。

1 つのプロバイダーだけを実行できますか？ はい。使いたいプロバイダーの API キーだけを設定してください。それ以外はすべて通知なしでスキップされます。設定なしですぐに利用するには、そのままインストールして開始してください。DuckDuckGo と Yahoo がキーなしで検索を処理します。

Docker は必要ですか？ いいえ。pip install argus-search を実行すれば、Python 3.11 以降がインストールされたマシンですぐに動作します。Docker が必要なのは、SearXNG（.env で ARGUS_SEARXNG_ENABLED=true を設定）または Crawl4AI（ローカルでの JS レンダリング）を利用する場合のみです。

コントリビューターはどの Python バージョンを使うべきですか？ リポジトリの開発と検証には Python 3.12 を使用してください。uv sync --python 3.12 --extra dev --extra mcp を実行してから、uv run pytest tests/ -v --tb=short を実行します。公開パッケージは引き続き Python 3.11 以降をサポートします。

ネットワーク上に Argus をデプロイする最も安全な方法は何ですか？ Tailscale などのプライベートネットワークを使用し、信頼できるインターフェースを明示的にバインドして、ARGUS_API_KEY を設定し、/api/admin/* には ARGUS_ADMIN_API_KEY を使用してください。インターネットへの直接公開は、リバースプロキシの背後で行う高度な運用モードとして扱ってください。

ライセンス

MIT — リリース履歴については、CHANGELOG.md を参照してください。