エージェントへのツール追加が面倒すぎる問題
エージェント開発で最も消耗する作業の一つが、ツール追加に伴う認証と権限管理です。トークンを発行し、スコープを絞り、危険な呼び出しには承認ゲートを噛ませる。これを手作業でやっていると、本来書くべきエージェントのロジックに割く時間が消えていきます。
Vercelが公開した @github-tools/eve-extension は、この反復作業を設定ファイル1つに圧縮する試みです。パッケージを追加し、agent/extensions/ にファイルを1つ置けば、GitHubツールセットがエージェントに組み込まれます。
重要なのは、ツール登録・認証・スコープ・承認ルールが単一の宣言的設定に集約されるという点です。これは単なる便利機能ではなく、エージェントが「どの権限で何をできるか」をコードレビュー可能な形で残す構造的変化です。本番デプロイのリスク管理という観点は、AIが生成したコード、そのままデプロイすると起きる災害とVercelの解法で詳しく扱っています。
根拠資料: Vercel Changelog - GitHub tools eve extension
インストールと登録の2ステップ
まずパッケージを追加します。
# パッケージのインストール
pnpm add @github-tools/eve-extension
続いて agent/extensions/ 配下にファイルを作成し、拡張を登録します。
// agent/extensions/github.ts
import githubExtension from '@github-tools/eve-extension'
export default githubExtension({
// Vercel Connectコネクタを指定（実行時に短命スコープトークンを発行）
connector: 'github/my-connector',
// code-reviewプリセットが必要なスコープを自動マッピング
preset: 'code-review',
// 書き込みツールごとの承認ルール: predicateによる条件付きも可能
requireApproval: {
// 自組織外へのコメント時のみ承認を要求
addPullRequestComment: ({ toolInput }) => toolInput?.owner !== 'vercel-labs',
},
})
このファイル1つで code-review ツールセット全体が登録されます。ファイル名がそのまま名前空間となるため、エージェント内部では github__addPullRequestComment のような名前でツールが公開されます。パッケージをアップグレードすれば新しいツールと修正が自動的に反映され、設定スキーマはimport時に検証されます。
プリセットがスコープを代行する
実務で最もありがたい部分がここです。プリセットごとに必要なConnectスコープが事前にマッピングされているため、トークンは必要最小限の権限のみを保持します。
| プリセット | 用途 |
|---|---|
code-review | PRレビュー、コメント、コード検討 |
issue-triage | Issue分類、ラベリング |
repo-explorer | リポジトリ構造の探索、ファイル参照 |
ci-ops | CIパイプライン操作 |
maintainer | メンテナ相当の管理作業 |
connector にVercel Connectコネクタを渡すと、拡張は実行時に短命かつスコープ制限されたGitHubトークンを発行します。長期トークンをコードに埋め込むアンチパターンがここで消えます。
承認ルールは設定と一緒に移動する
エージェントが本当に危険なのは書き込み操作です。読み取りは失敗してもデータは変わりませんが、コメント投稿・PR作成・Issueクローズは取り返しがつきません。
この拡張はすべての書き込みツールに対してデフォルトで承認を要求します。さらに3つの方式でゲートを細かく制御できます。
always: 毎回人手承認once: セッションごとに1回のみ承認- predicate関数: 入力値に応じた条件付き承認（例: 自組織外へのコメント時のみ）
上記の例で addPullRequestComment に付与したpredicateがまさにそのケースです。toolInput?.owner !== 'vercel-labs' が真のときのみ承認を要求するため、内部リポジトリでは摩擦なく動作し、外部リポジトリでは人が介入します。
注意事項
- predicateは純粋関数に保ってください。 ここで外部API呼び出しや状態変更を行うと、承認フローが予測不能になります。
- プリセットのスコープは最小権限ですが、常に「最小」とは限りません。
maintainerプリセットは名前通りの権限を持つため、本番エージェントには本当に必要なプリセットのみを付与してください。 - トークンが短命であることは良い知らせであると同時に運用負荷でもあります。 コネクタ自体の可用性がエージェントの可用性に直結します。
エージェントツールの承認フローをテスト戦略とどう結びつけるかは、従来のテストの終焉？エージェント開発時代を支えるJITテスティングの台頭で扱っています。
次の学習ステップ
- Vercel Connectコネクタの作成から始め、ご自身のGitHub組織に接続してみてください。
code-reviewプリセットで開始し、承認ログを数日観察したうえでpredicate条件を絞り込んでください。- 慣れてきたら
ci-opsやmaintainerプリセットを別エージェントに付与し、権限を分離する構成へ拡張してください。
この拡張が投げかけるメッセージは明確です。エージェントの権限はプロンプトではなく設定ファイルに明示されるべきである。 それがレビュー可能で、監査可能で、巻き戻し可能な構造だからです。