権限・サンドボックス・並列サブエージェント・スキル/プラグインで、エージェント運用を一段引き上げる
agy CLI の上級機能を手を動かして体験します。各コマンド・パス・ショートカットの詳細は CLI リファレンス(日本語要約) も併せて参照してください。
agy)は新しいプロダクトで、コマンド名・フラグ・設定ファイルのパス・キーバインド・JSON のキー名などはバージョンによって変わる可能性があります。本ページの具体値は執筆時点の公式ドキュメントに基づきますが、変わりうる箇所には 要確認 を付けています。実施前に antigravity.google の最新ドキュメントをご確認ください。
gca-handson/antigravity/starter/(または完成版 completed/)を File → Open Folder で開き、統合ターミナルで agy を起動した状態を前提とします。グローバル設定は ~/.gemini/antigravity-cli/settings.json、ワークスペース設定は .agents/ 配下です。
fine-grained permissions と Terminal Sandbox で、エージェントの「実行できる範囲」を設計する
action(target) という権限リソースとして表現され、allow / deny / ask の 3 リストで評価されます。優先順位は Deny > Ask > Allow。さらに Terminal Sandbox(Linux は nsjail / macOS は sandbox-exec / Windows は AppContainer)でコマンド実行を OS レベルで隔離できます。安全に「攻めた自動化」を行うための土台です。
/open で外部エディタに開くか、IDE で直接開きます:# パスは ~/.gemini/antigravity-cli/settings.json agy # プロンプトで: /open ~/.gemini/antigravity-cli/settings.json
permissions ブロックを次のように設定します。deny に破壊的コマンド、allow に日常的に使う安全なコマンド、判断が要るものは ask に置きます:// ~/.gemini/antigravity-cli/settings.json { "permissions": { "allow": [ "command(git)", "command(npm run (build|lint|test))", "read_url(google.com)" ], "deny": [ "command(rm -rf)", "command(sudo)", "write_file(.git/)" ], "ask": ["command(*)"] } }
ask に command(*) があり allow に command(git) があります。Ask は Allow より優先されるため、allow に挙げていないコマンドはすべて確認が入ります(git は allow されているので素通り)。一方 deny の command(rm -rf) / command(sudo) は常にブロックされ、確認すら出ません。
command(...) はトークン単位の前方一致で、各トークンが ^(?:pattern)$ のアンカー付き正規表現として評価されます。例えば command(npm run (build|lint|test)) は npm run build / npm run lint / npm run test にマッチします。ファイル系(read_file / write_file)はワークスペース内が既定で auto-allow、ワークスペース外や URL(read_url / execute_url)は既定で Ask です。
settings.json に、権限モードを proceed-in-sandbox に、サンドボックスを true にする設定を追記します:// ~/.gemini/antigravity-cli/settings.json { "toolPermission": "proceed-in-sandbox", "enableTerminalSandbox": true }
agy を起動し直します(Cloud Workstation の Linux 環境では nsjail で隔離されます)。request-review(既定): すべての書き込み・コマンド・リモート通信の前に確認。proceed-in-sandbox: すべてのコマンドをサンドボックス内で実行。安全なものは自動実行、危険なものは確認。strict: 読み取り以外のすべてで確認(行単位の完全な透明性)。/permissions パネルの表記(always-proceed など)と差異がある場合があります。実際の選択肢は /permissions で確認してください。
deny に入れたコマンドをエージェントに依頼し、即座にブロックされることを確認します(実害はありません):command(rm -rf) が deny にあるため、エージェントは実行できず、別の安全な方法(個別 git clean の提案など)に切り替えるはずです。allow に挙げていないコマンドを依頼し、確認カードが出ることを見ます:# サンドボックス有効時のプロンプト例
Do you want to proceed?
1. Yes
2. Yes, and run without sandbox restrictions
3. No
unsandboxed(prefix) を allow に追加します(例: unsandboxed(git push))。これはサンドボックス有効時のみ意味を持ちます。
非対話の -p フラグで、エージェントをシェルパイプラインや Git フックに組み込む
agy -p "..." は対話 TUI を開かずに1 回だけプロンプトを実行して結果を標準出力に返します。Git フック・CI・スクリプトに組み込むことで、「コミットメッセージ草案」「差分レビュー」「リリースノート生成」などを自動化できます。
app.py に何か変更を加えた状態(または小さな変更を git add した状態)で、ターミナルから直接実行します:# 公式ドキュメント記載の例(そのまま使えます) agy -p "Review this git diff and draft a conventional commit message" --cwd $(pwd)
feat: / fix: など)のメッセージ案を標準出力に返します。気に入ったら手動でコミットに使います。--cwd が効くポイント--cwd $(pwd) でワークスペースのルートを明示すると、エージェントは AGENTS.md や対象ファイルを正しく解決できます。フックやスクリプトから呼ぶときは、カレントディレクトリが意図と違うことがあるため常に明示するのが安全です。
prepare-commit-msg フックを作り、コミット時にメッセージ草案を自動生成します。.git/hooks/prepare-commit-msg を作成します:#!/usr/bin/env bash # .git/hooks/prepare-commit-msg # ステージ済み差分から Conventional Commit のメッセージ案を生成し、 # コミットメッセージファイルの先頭に挿入する COMMIT_MSG_FILE=$1 # ステージ済みの差分がある場合のみ実行 if git diff --cached --quiet; then exit 0 fi DRAFT=$(agy -p "Review the staged git diff and output only a single-line conventional commit message" --cwd $(pwd)) # 既存メッセージの前に草案を差し込む printf '%s\n\n%s\n' "$DRAFT" "$(cat $COMMIT_MSG_FILE)" > $COMMIT_MSG_FILE
chmod +x .git/hooks/prepare-commit-msg
git add し、git commit を実行します。エディタが開くと、先頭に草案メッセージが入っているはずです。agy -p は対話できないため、確認待ち(ask)で止まると失敗します。フックで使うなら、必要な操作(差分読み取り程度)が allow 済みであることを確認してください。また実運用ではレイテンシも考慮し、巨大な差分ではタイムアウト対策を入れると安心です。
-p に渡し、リリースノートの下書きを作ります。パイプで履歴を渡すこともできます:# 直近タグからのコミットを基にリリースノートを生成 git log $(git describe --tags --abbrev=0)..HEAD --oneline \ | agy -p "Summarize these commits into Markdown release notes grouped by Added / Changed / Fixed" --cwd $(pwd) \ > RELEASE_NOTES.md
RELEASE_NOTES.md を確認し、必要に応じて手直しします。CI の「タグ push 時」ステップに組み込めば、リリースノート草案を自動で添付できます。agy -p は終了コードと標準出力を返すので、GitHub Actions / Cloud Build の 1 ステップとして扱えます。レビュー結果を PR コメントに投稿したり、生成物をアーティファクトとして保存したりと、既存のパイプラインに自然に挿し込めます。要確認(CI 環境での認証方法は公式ドキュメントで確認)
主エージェントにサブエージェントを fan-out させ、複数の改善を並行して進める
/agents パネルで進捗を監視し、承認が必要な箇所だけ素早くさばけます。
app.py(対応履歴機能つき)に対し、独立した複数タスクを並列で進めるよう主エージェントに依頼します:/agents と入力して Agent Manager パネルを開きます。実行中・完了・失敗の各サブエージェントが、ID・役割・状態・現在のステップ付きで一覧表示されます:↑/↓ で対象サブエージェントを選び Enter で Subagent Detail View に入ると、内部の思考ログ・ツール呼び出し・実行出力まで読めます。Esc で一覧に戻ります。/tasks で監視します。stdout ログの確認や、暴走プロセスの安全な停止ができます:Subagent 12 asks to run "pytest")が表示されます。ctrl+k を押すと、保留中のアクションを即座に承認できます。ctrl+k のほか alt+j があります(承認待ちのサブエージェント間の移動に使えるとされますが、alt+j の正確な機能は公式に明記されていません — 要確認)。確認/却下したら Esc で元のスレッドに戻ります。なお ctrl+j は公式のキーバインド一覧には含まれていません。ctrl+r / ctrl+o / alt+j / ctrl+k で、承認は ctrl+k が確定です。ctrl+j はこの一覧に含まれず(「テレポート」の説明は AI 要約由来の誤りの可能性)、alt+j の正確な機能も公式には未記載です。実際の割り当ては /keybindings または /help のショートカットタブで確認してください。
/agents で全体像を掴み、Fast Path Alert が出たら ctrl+k で即承認、深く見たいときだけ Detail View で内容を確認、というリズムを身につけると、複数改善を一気に回せます。
スキルを / コマンド化し、プラグインとして skills/agents/rules/MCP/hooks を一括配布する
/<name> スラッシュコマンドになります。プラグインは skills / agents / rules / MCP 定義 / hooks を 1 つの配布可能なバンドルにまとめた仕組みです。チームの規約や定型作業を「インストールするだけ」で全員に配れます。
antigravity/starter/)に .agents/skills/ ディレクトリを作り、code-review.md を作成します:mkdir -p .agents/skills
.agents/skills/code-review.md に frontmatter(name / description)と指示を書きます。name がそのまま / コマンド名になります:# .agents/skills/code-review.md
---
name: code-review
description: お問い合わせ管理 API のコードを規約とセキュリティ観点でレビューする
---
あなたはこのリポジトリのレビュアーです。AGENTS.md の規約に従い、
変更(または指定ファイル)を次の観点でレビューしてください:
1. SQL: f-string や % 演算子で SQL を組み立てていないか(必ずパラメータ化クエリ)
2. バリデーション: 文字列フィールドの最大長・許可リスト検証があるか
3. エラーハンドリング: {"error": "..."} 形式と適切な HTTP ステータスか
4. docstring: 全関数に Google Style の docstring があるか
指摘は「ファイル:行 / 重大度 / 修正案」の形式で簡潔に出力してください。
agy を起動するとスキルがコンパイルされ、/code-review が使えるようになります。/skills で登録状況を確認できます:.agents/skills/ に置いたスキルはリポジトリと一緒に git 管理でき、チームで共有されます。全ワークスペースで使いたい個人用スキルは ~/.gemini/antigravity-cli/skills/ に置くと、どのディレクトリで agy を起動しても / コマンドとして読み込まれます。
code-review.md を skills/ に入れ、rules/ に AGENTS.md 相当の規約を、hooks.json にフォーマッタ実行などを束ねれば、チーム規約一式を 1 つのプラグインとして配布できます。/ コマンド」を配るのに向きます。プラグインは skills / agents / rules / MCP / hooks をまとめて配るバンドルで、「このプロジェクトに参加したら、これを入れるだけ」というオンボーディングの単位になります。
agy plugin(複数形 plugins も可)サブコマンドで、プラグインの一覧・インストール・有効化/無効化・アンインストールを行います:# インストール済みプラグインの一覧 agy plugin list # ローカル(またはリモート)パッケージをインストール agy plugin install /path/to/local/plugin # 一時的に無効化 / 再有効化(アセットは残る) agy plugin disable <plugin_name> agy plugin enable <plugin_name> # 完全に削除(ディレクトリとレジストリを掃除) agy plugin uninstall <plugin_name>
/skills や /hooks、/mcp でプラグインが提供するコンポーネントがロードされているか確認します。.agents/)の順で適用されます。同名の / コマンドがある場合の優先順位や、フックの実行順序はバージョンで変わりうるため、/skills / /hooks パネルで実際のロード状況を確認してください。
Model Context Protocol で、エージェントにローカル API や DB ツールを安全に接続する
.agents/mcp_config.json に置きます(グローバルは ~/.gemini/antigravity-cli/mcp_config.json)。題材アプリの SQLite を読む例:// .agents/mcp_config.json { "mcpServers": { "sqlite-explorer": { "command": "node", "args": ["/usr/local/bin/sqlite-mcp-server.js"], "env": { "SQLITE_DB_PATH": "/var/data/app.db" } } } }
/mcp で MCP Manager Overlay を開き、サーバーの状態(active / disconnected / loading)を確認します。必要なら設定を再読み込みします:serverUrl フィールドを定義してください。レガシーな url / httpUrl はサポートされません。
mcp(server/tool) や mcp(*) を allow / deny / ask に書けます(例: mcp(sql/execute_mutation) を ask にして書き込み系だけ確認を入れる)。
スクリーンショットをプロンプトに貼り、UI 崩れをエージェントに診断・修正させる
ctrl+v を押すと、エージェントがそのメディアを参照して原因を診断します。
/tickets/1/view(対応履歴つきの詳細ページ)を開きます。意図的に CSS を 1 行壊すか、表示が崩れている箇所のスクリーンショットを撮ります。agy のプロンプトボックスにフォーカスし ctrl+v で添付します。続けて指示を書きます:@templates/ticket_detail.html(どこを直すか)を同時に渡すと、エージェントは探索範囲を絞り込めます。視覚情報とファイル参照の併用が、視覚デバッグの精度を上げるコツです。
セッションを分岐して実装案を比較し、行き詰まったら安全な地点へ戻す
/fork で並行セッションに分岐して試せます。ビルドエラーが続くなど行き詰まったら /rewind(別名 /undo)で安定していた地点まで巻き戻せます。
/fork で複製した並行セッションを立ち上げます:/resume(別名 /switch)で安定したメインのスレッドへ戻り、案 B(例: 既存 LIKE のまま正規化を強化)を試します。両者の差分を見比べて採用案を決めます。/fork は「失敗しても元に戻れる」ため、思い切った実装を試しやすくなります。A/B どちらも実物のコードで比較できるのが、口頭の議論との大きな違いです。
esc でその場でターンを中断するのも有効です。-p で自動化し(M2)、並列サブエージェントで一気に改善し(M3)、スキル/プラグインでチームに展開する(M4)。さらに MCP(M5)・視覚デバッグ(M6)・/fork・/rewind(M7)で表現の幅が広がります。基礎で身につけた「計画→承認→実行→検証」を、これらの上級機能でスケールさせてください。