【ブリッジ】外部エージェント連携 — KASUGAI Canvas ドキュメント

1. 概要 — 【ブリッジ】とは

【ブリッジ】系統は、チャットの POST /agent をローカルのブリッジハブ（常駐の bridge-hub.exe :8511 — アプリ版・ブラウザ WebGIS 共通の1本）が受けて外部 CLI（copilot / devin / agy）へ中継する方式です。ブラウザからモデルへ直接接続する代わりに、公式 SDK / CLI をローカルブリッジ経由で利用するため、ブラウザに API キーは不要で、既存の Copilot 契約や自作エージェントをそのまま繋げます。専用プロバイダの選択肢はハブを検出できる環境でのみ表示されます。

内蔵AI（Gemini・OpenAI互換）による公式 API 直通は【API】内蔵AI、接続方式ごとの規約判断は「5. 注意点・制限」を参照してください。

2. 導入・セットアップ — ブリッジハブのインストール

アプリ版（kasugai_canvas.exe）— 追加導入は不要

アプリ版はハブを内蔵しません。インストール済みの bridge-hub.exe（127.0.0.1:8511 常駐）があれば、アプリ起動時に未起動でも自動で起動されるため、ハブを一度インストールすればアプリ側でもそのままブリッジが使えます。ハブ自体は「【ブラウザ WebGIS】bridge-hub.exe」で示す手順で導入します（アプリ本体（既定 :8510）の終了後も常駐を続けます）。

ブラウザ WebGIS / 通常版 — bridge-hub.exe を導入

静的配信・CDN のブラウザ WebGIS からブリッジ系プロバイダを使うには、ブラウザと同じ PC に単体のブリッジハブを常駐させます。Rust 製の単一 exe（bridge-hub.exe）のため Node.js は不要です。

DOWNLOAD: bridge-hub.exe（CDN・自己インストール型）

基本は「ダウンロード → 実行」の2操作で完結します。実行すると %LOCALAPPDATA%\kasugai\bridge-hub\ へ自己インストールされ、ログイン時自動起動の登録（タスク KasugaiCanvasBridgeHub・登録できない環境では HKCU Run キー）＋即時起動（ポート 8511・コンソール非表示）＋ブリッジ用 CLI（copilot/devin）未導入分の自動インストールまで一括で行われます（--no-cli-setup で CLI 導入を省略可）。管理者権限は不要です。AI 設定画面でブリッジ系プロバイダを選ぶとハブ未検出時にこのダウンロードが自動で始まり、実行後はフロントが /health のポーリングで検出して接続まで自動完了します。

bridge-hub.exe をダウンロードして実行（AI 設定画面の「ハブを自動インストール」ボタン・ダウンロードリンク、または上のリンクから取得。実行は最初の1回のみ）
解除は bridge-hub.exe --uninstall（自動起動解除＋停止＋インストール先の削除）。起動後、Canvas の管理（⚙）→ AI → チャットで「AI プロバイダ」に「GitHub Copilot」「Devin」「Antigravity」が表示されます（フロントが同一 PC の :8511 の /health を疎通して検出）

自動機・スクリプトからの導入（bridge-hub.zip）

AI エージェント・スクリプトからの無人導入は download/bridge-hub.zip（bridge-hub.exe＋README のみ。スクリプト同梱は廃止しました — exe は GUI subsystem でコンソールを持たないため vbs/ps1 は不要です）を使い、すべてコマンドで完結します（対話が必要なのは各プロバイダ CLI への本人ログインのみ）:

$dst = "$env:LOCALAPPDATA\kasugai"
Invoke-WebRequest "https://yamamoto-ryuzo.github.io/kasugai-canvas-web/stable/download/bridge-hub.zip" -OutFile "$env:TEMP\bridge-hub.zip"
Expand-Archive "$env:TEMP\bridge-hub.zip" $dst -Force
Get-ChildItem -Recurse "$dst\bridge-hub" -File | Unblock-File
& "$dst\bridge-hub\bridge-hub.exe" --install
& "$dst\bridge-hub\bridge-hub.exe" --setup all
1..15 | % { try { Invoke-RestMethod http://127.0.0.1:8511/health -TimeoutSec 2; break } catch { Start-Sleep 1 } }

bridge-hub.exe --install は自動起動登録（8511）＋即時起動＋ブリッジ用 CLI 導入まで非対話で行います（--no-cli-setup で CLI 導入を省略可）。exe 単体をダウンロードして --install 実行でも同じです（zip 展開は不要）
インストールせずその場でハブを起動する場合は bridge-hub.exe --serve（環境変数 BRIDGE_HUB_PORT 指定時も裸実行は起動のみ）。CLI 導入のみは --setup all、状態確認は GET /setup・GET /health、解除は --uninstall
端末から引数付きで実行すると親コンソールへ出力を戻します（GUI subsystem のため常駐起動では何も表示されず、引数なし実行の結果はメッセージボックスで通知されます）

ハブは 8511 に一本化済み（旧ブラウザ WebGIS 用の 8512 常駐ハブは廃止 — ハブ側・アプリ側の起動時掃除で自動停止されます）。エージェントからのプロバイダ別 CLI 導入・状態確認はハブの GET/POST /setup API からも実行できます。

プロバイダ別 CLI の導入

各プロバイダは実際に使われた時点で対応する外部 CLI を子プロセス起動します。ハブの /setup API で公式手順の自動導入もできます（Canvas の AI 設定画面の「CLI を自動インストール」ボタン、または bridge-hub.exe --setup copilot|devin|all）。

プロバイダ	必要なもの	認証
GitHub Copilot	`copilot` CLI（npm 版は Node.js も必要）＋Copilot 契約（Free〜Enterprise）	`copilot` CLI で対話ログイン済み、または gh CLI ログイン済みなら `login --with-token` で自動登録（v6.5.17〜）
Devin	`devin` CLI（Devin Desktop 同梱または単体。`DEVIN_CLI_PATH` で指定可）＋本人の Devin プラン	サービスユーザー APIキー（`cog_`・チームプランのみ・`DEVIN_API_KEY` またはアプリ設定画面。PAT は拒否）または初回接続時のブラウザ PKCE ログイン（キー失敗時も自動フォールバック・v6.5.17〜）
Antigravity	`agy` CLI（Antigravity のインストールに同梱。`AGY_CLI_PATH` で指定可）	利用者自身の Google アカウントでの `agy` ログイン（一度対話起動してサインイン）
外部エージェント（汎用）	なし（ハブ不要・エンドポイント URL だけ設定）	エンドポイント側の仕様に従う（Bearer トークン任意）

Copilot・Devin CLI はハブ経由で自動導入可能（copilot: winget → npm → 直接DL の順にフォールバック。devin: 公式インストーラ）。Antigravity は IDE インストーラ＋対話ログインのため案内のみです。

3. 使い方 — プロバイダ別の接続手順

共通の流れ: 管理（⚙）→ AI → チャットで「AI プロバイダ」を選んで保存するだけです。ADK 等のフレームワークは内蔵せず、外部で構築されたエージェントを API で呼び出す構成のため、アプリが担うのはチャット UI・地図操作・応答往復のみです。

🤝 外部エージェント（汎用 /agent）

「AI プロバイダ」を「外部エージェント (ブリッジ)」にし、ブリッジ欄にエンドポイントURL・Bearerトークン（任意）を設定して保存すると、チャット入力がそのエンドポイントへ POST されます。要求JSONは {message, project, camera, layers, history, tools}（tools は現在公開中のツール宣言・functionDeclarations 形式）、応答JSONは {reply, actions:[{name,args}]} で、actions はAIチャットと同名のツール（flyTo・setLayerVisible 等）として順次実行されます。エンドポイント側ではこのオリジンからの CORS 許可が必要です

🐙 GitHub Copilot

「AI プロバイダ」に「GitHub Copilot」を選んで保存すれば、疎通したブリッジへ自動接続され Copilot を内蔵AIとして利用できます。常駐のブリッジハブ（:8511）が待受け、選択時にハブ内の Copilot ブリッジ（copilot CLI への stdio 接続）が起動します（要 Copilot サブスクリプション＋copilot CLI）。ブラウザ WebGIS でも同一 PC の bridge-hub（:8511）が動いていれば同じ選択肢が出ます

🧠 Devin

「Devin」を選択して保存すると、ブリッジハブ（127.0.0.1:8511）経由でハブ内の Devin ブリッジが起動・接続されます。ブリッジは devin acp に対して ACP 認証を行い、利用者自身のアカウントでモデルを利用します。ブラウザ認証または本人の DEVIN_API_KEY を使用し、ローカル CLI のログインだけに依存しません。接続方式の判断・利用条件と M365 を見送った理由も参照してください

🪐 Antigravity

「Antigravity」を選択して保存すると、ブリッジハブ経由でアプリ内の Antigravity ブリッジが起動・接続されます。ブリッジは Antigravity CLI（agy）の headless 実行（stream-json）を駆動し、利用者自身の Google アカウントでの agy ログインと quota でモデルを利用します。ブリッジが agy mcp add で地図ツールを MCP として登録し、permissions.allow に mcp(kasugai/*) を追加します（headless では未許可ツールが自動拒否されるため必須）。会話はプロジェクト単位で継続します

逆方向の「外部 → ブラウザを操る」はアプリ本体（127.0.0.1:8510）の /api/command 経路です。

4. ブリッジハブの構成（待受ポート・検出・環境変数）

ポートと検出

ハブはアプリ版・ブラウザ WebGIS 共通で :8511 の1本に集約（旧 8512 常駐ハブは廃止）。フロントは :8511 の /health を疎通してハブ（hub:true）を検出します。ハブの全 API・CLI フラグ・詳細仕様はブリッジハブ（bridge-hub.exe）、ハブに集約した設計判断（3ポート分離との比較・マルチエージェント観点）は V3: 設計判断：ブリッジハブを参照してください。

環境変数

変数	既定	説明
`BRIDGE_HUB_PORT`	8511	ハブの待受ポート（127.0.0.1 のみバインド）。アプリ・ブラウザ WebGIS 共通の統一ポートなので変更不要（変更時はブラウザが検出できなくなる点に注意）
`KASUGAI_NO_COPILOT_BRIDGE`	なし	copilot プロバイダを無効化
`KASUGAI_NO_DEVIN_BRIDGE`	なし	devin プロバイダを無効化
`KASUGAI_NO_ANTIGRAVITY_BRIDGE`	なし	antigravity プロバイダを無効化

5. 注意点・制限 — AI 接続方式と利用規約上の判断

接続方式ごとの判断

判断対象は「この接続方式でサービスに接続し、提供されるモデルを利用することが禁じられているか」です。以下は各利用者が自分のアカウントで正規認証し、利用可能なモデルを契約の利用枠内で使う構成についての判断です。OSS アプリ・自作ブリッジの配布と、配布者の AI アカウントの共有・AI サービス自体の再販は区別します。

接続方式	公式資料の根拠	本プロジェクトの判断
GitHub Copilot：アプリ → ブリッジ → 公式 SDK / Copilot CLI → モデル	SDK 認証ガイドが、本人のログイン資格情報を使うデスクトップアプリ・開発／テスト環境を明示的に想定。	採用。公式に想定された接続方式であり、この方式でのモデル利用を禁止する規定は確認されていません。
Devin：アプリ → ブリッジ → `devin acp` → モデル	公式 ACP 連携ガイドが、ACP 対応クライアントからの子プロセス起動とブラウザ認証を案内。	採用。公式の外部接続機構を使用しており、この方式でのモデル利用を禁止する規定は確認されていません。KASUGAI 自体が Cognition の公式製品・認定連携という意味ではありません。
Antigravity：アプリ → ブリッジ → `agy`（headless）→ モデル	公式 headless モードガイドが、スクリプト・CI・外部プログラムからの非対話実行（stream-json 入出力）を明示的に案内。MCP サーバー登録（`agy mcp add`）も公式機構。	採用。公式に想定された外部接続機構を使用しており、この方式でのモデル利用を禁止する規定は確認されていません。ローカル・本人利用限定（自分のアカウント quota で自分のチャットのみ処理）。KASUGAI 自体が Google の公式製品・認定連携という意味ではありません。

上記の GitHub Copilot / Devin / Antigravity 経路について、ブリッジを挟むこと、自作 OSS アプリから呼ぶこと、通常の機能確認・回帰テストで自動呼び出しすること自体を一律に禁じる条項は、確認した資料には見当たりません。本人の利用枠・レート制限・組織ポリシーを守り、制限回避や第三者向けの共有バックエンド運用は行わない前提です。モデルへの会話・カメラ・レイヤー情報の送信自体を不採用理由にはしません（送信権限があり、サービスの禁止データに該当しないことが前提）。アクセス制御やツール制限の実装品質は、接続方式の可否とは別に確認します。

根拠となる規約：GitHub 追加製品規約（Copilot の契約別適用先）・GitHub 利用規約・GitHub AUP・Cognition 利用規約（§2）・Cognition AUP。

M365 / Microsoft Copilot を見送った理由

「M365 のモデル利用そのものが禁止」ではありません。以前検討した Web UI 自動化と、条件を満たして使う公式 API を分けて判断します。GitHub Copilot と Microsoft 365 Copilot は別サービスです。

消費者向け Microsoft Copilot の Web UI 自動化：規約上の禁止が理由。Microsoft Copilot 使用条件の「WHO CAN USE COPILOT」は “Don’t use tools or computer programs (like bots or scrapers) to access Copilot.” と明示しています。画面への自動入力・送信・応答取得をブリッジ化する方式は採用しません。本人アカウント・ローカル利用だけでこの制限が解除されるわけではありません。
職場・学校向け M365 Copilot の Web UI 自動化：正規のプログラム接続経路として採用しない方針。上記の消費者向け規約は、職場・学校・組織（Entra）アカウントには適用しないと明記されています。その条項を根拠に M365 も一律禁止とは断定しません。Web UI 自動化の許諾を確認できていない経路や、認証・アクセス制御・ボット対策の回避を前提とする経路は提供せず、連携を追加する場合は公式 API と適用契約に従います。
M365 Copilot 公式 Chat API：禁止ではなく、導入条件により標準連携を見送り。公式 Chat API（プレビュー）は自作アプリへの組み込みを想定しています。ただし、Microsoft 365 Copilot アドオンライセンス・アプリ登録・職場／学校アカウントの委任アクセスと必要権限への同意が前提です。確認時点の chat API 仕様では7権限すべてが必要で、個人 Microsoft アカウント・アプリケーション権限（ユーザーなしの app-only）は非対応です。

必要な7権限：Sites.Read.All・Mail.Read・People.Read.All・OnlineMeetingTranscript.Read.All・Chat.Read・ChannelMessage.Read.All・ExternalItem.Read.All。このうち ChannelMessage.Read.All などは管理者同意が必須であり、利用者が自分でログインするだけでは導入できません。管理者同意が必要ということと、実際の利用者本人が管理者でなければならないということは別です。

このため、組織の事前設定なしで使える標準ブリッジとしては見送っています。ライセンス・管理者同意等を整え、M365 Copilot APIs 使用条件に従う公式 API 連携は別途検討可能です。確認時点では /beta API で本番利用は非サポートと案内されており、製品への採用時には提供状況の再確認も必要です。

確認日：2026年10月13日。上記は公開規約・公式資料に基づく接続方式の判断であり、提供元による本アプリの個別承認や、用途を問わない適合保証ではありません。個別契約・組織ポリシー・規約改定がある場合はそれらを確認してください。

KASUGAI Canvas v6.17.0