agent-browser

AIエージェント向けの堅牢化されたローカルブラウザ。依存関係ゼロ。 お使いのChromeをDevToolsプロトコル経由で操作し、トークン効率の良いMarkdownを抽出します。自動化ツールとして簡単に検出されることはありません。

npx -y @truenix/agent-browser markdown https://news.ycombinator.com

すべてローカルで動作します。アカウント不要、APIキー不要、リモートサービス不要、割り当て枠なし。

なぜ

エージェントに生のHTMLを渡すと、トークンの大部分が無駄になります。実際のページで測定した結果:

さらに、自動化として自己申告するブラウザは、検出されたり、異なるコンテンツを配信されたりします。これは、エージェントが受け取るデータを静かに劣化させます。

Related MCP server: Browser-MCP Navigator

インストール

MCPサーバーとして

claude mcp add browser -- npx -y @truenix/agent-browser mcp

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@truenix/agent-browser", "mcp"]
    }
  }
}

npm install @truenix/agent-browser

ツール: browser_markdown、browser_html、browser_links、browser_screenshot、browser_pdf、browser_console、browser_probe

ライブラリとして

import { withBrowser } from '@truenix/agent-browser';

const md = await withBrowser({}, async (session) => {
  await session.navigate('https://example.com');
  return session.markdown();
});

npx -y @truenix/agent-browser install          # edits ~/.dsh/profiles/web/cordis.patch.yml + package.json, then pnpm install
# npx -y @truenix/agent-browser install --profile web --dry-run  # preview
# npx -y @truenix/agent-browser uninstall      # remove again

DSH / Cordisプラグインとして

ワンライナー（推奨 — DSH環境では自動で配線されます）:

npm i -g @truenix/agent-browser
# or inside the harness checkout: pnpm add @truenix/agent-browser

browser_markdown、browser_html、browser_links、browser_screenshot、browser_evaluate がDSHのホストにネイティブツールとして表示されます。npx を手動で実行する必要はありません。

手動設定（コンポジションを自分で編集したい場合）:

# ~/.dsh/profiles/web/cordis.patch.yml  — persists for every web session
- insert:
  - id: agent-browser
    name: '@truenix/agent-browser/cordis'
    config:
      timeoutMs: 180000   # per-tool call budget; default respects AGENT_BROWSER_BIN / ENDPOINT
      # cli: 'npx -y @truenix/agent-browser'  # override only if needed

Cordisプラグインの設定:

- '@truenix/agent-browser/cordis':
    timeoutMs: 180000

設定キー:

agent-browser <command> [options]

  markdown <url>     Extract the page as Markdown (main content by default)
  text <url>         Visible text only
  html <url>         Full serialized DOM after JavaScript runs
  links <url>        Every anchor as JSON
  screenshot <url>   PNG/JPEG   (-o file, --full)
  pdf <url>          PDF        (-o file)
  a11y <url>         Filtered accessibility tree
  eval <url> <expr>  Evaluate JS in the page
  probe              Browser, GPU and capability report
  mcp                Run as an MCP server on stdio

CLI

agent-browser markdown <url> [options] — ページをMarkdownとして取得します。

agent-browser html <url> [options] — 加工前のHTMLを取得します。

agent-browser links <url> [options] — ページのリンクを抽出します。

GXP11

オプション: --headful、--no-stealth、--block-images、--gpu/--no-gpu、--width、--height、--viewport WxH、--main、--raw、--full、--endpoint <url>、--timeout <ms>、--json、-o

--endpoint はブラウザを起動せずに既存のブラウザへ接続します。多くの呼び出しにまたがって1つのブラウザを再利用するのに便利です。

検出回避

通常のヘッドレスChromeとは異なり、navigator.webdriver が false のままになります。 生のCDPは --enable-automation フラグを追加しないため、navigator.webdriver は undefined のままです。ただし、それをさらに強化するための対策がいくつかあります。

強化された条件で bot.sannysoft.com を実行すると、合格 となります。 bot-detector.rebrowser.net も同様に 合格 です。

検出について

検出は、以下の2つの大きなカテゴリに分けられます。

1. JavaScript による検出 — navigator.webdriver、プロパティの欠落、Chrome DevTools Protocol の起動時の痕跡。

2. ネットワークレベルのフィンガープリンティング — TLS フィンガープリント、IP 評判、HTTP/2 のフレーム順序。

このプロジェクトは カテゴリ1 に対処し、ブラウザをよりクリーンに、より標準的に見せます。カテゴリ2 はユーザー自身のネットワークの評判に依存するため、範囲外です。

CDP 検出

最も永続的な CDP 検出方法の1つは、Runtime.enable が呼び出された後に Error.stack が変更される ことです。Puppeteer と Playwright はどちらも Runtime.enable を呼び出すため、CDP 駆動のブラウザは起動直後に検出されます。

このプロジェクトは 決して Runtime.enable を呼び出しません。 代わりに、Runtime.evaluate を awaitPromise 付きで使用して、ページコンテキスト内のプロミスを解決します。これはクリーンな方法で、Runtime.enable の痕跡を残しません。

最新のテスト結果 (npm run test:bot)

技術的詳細

puppeteer-extra-plugin-stealth は使用していません。これは壊れやすい Function.prototype.toString のパッチに依存しており、多くのパッチ（chrome.runtime、permissions、languages など）は現代のChromeでは不要であるか、検出可能です。代わりに、オリジナルのChromeバイナリをフラグ付きで起動し、特定のCDPコールのみを使用します。

ゼロ依存関係

dependencies は空です。Nodeのグローバル WebSocket（Node ≥ 22）または組み込みの node:http を使用してCDPに接続します。Chromeの起動と管理には node:child_process、Markdownへの変換には独自のDOMウォーカーを使用します。

環境変数

GXP12

ライセンス

MIT