Antigravity CLIの始め方完全ガイド｜インストールから基本コマンド、自動化、トラブル対処まで

AIを使った開発支援ツールは、どんどん増えています。

ただ、チャット画面で答えをもらうだけではなく、

「そのままターミナル上で作業まで進めたい」

と感じる場面もありますよね。

たとえば、ファイル操作、コード生成、レビュー、自動化などです。

そこで気になったのが、AIエージェントとMCPを組み合わせて開発作業を進める Antigravity CLI です。

調べていくと、Antigravity CLIは単なる「AIチャットのCLI版」ではありませんでした。

ローカル環境、クラウドAI、外部ツールをつなぎ、エージェントに作業を任せるための仕組みとして設計されている印象です。

この記事では、Antigravity CLIについて、次の内容を順番に紹介します。

Antigravity CLIでできること
導入前に確認したい環境
インストールと初期設定
基本コマンドの使い方
開発ワークフローへの活用方法
自動化や拡張の考え方
トラブル対処とセキュリティ面の注意点

Antigravity CLIを使い始める前に全体像をつかみたい場合は、ぜひ参考にしてみてください。

目次−

Antigravity CLIとは何か：できることと全体像

Antigravity CLIの基本的な位置づけ

Antigravity CLIは、ローカル環境とクラウドAIエージェントをつなぎ、開発や運用タスクを自動化するための エージェント駆動型CLIツール です。

通常のAIチャットでは、ユーザーが質問を入力し、AIが回答を返します。

その回答をもとに、コードをコピーしたり、ターミナルでコマンドを実行したり、ファイルを書き換えたりするのは人間側の作業です。

一方、Antigravity CLIでは、ターミナルからAIエージェントに指示を出します。

そして、必要に応じてローカルファイルや開発ツールと連携しながら、タスクを進める流れを想定しています。

つまり、Antigravity CLIは単に 「答えをもらうツール」ではありません。

どちらかというと、「作業を進めてもらうためのCLI」 と考えると分かりやすいです。

主要コンポーネント：agy・API・MCP

Antigravity CLIの仕組みを理解するうえで、まず押さえておきたい構成要素が3つあります。

agy
Antigravity API
MCP

それぞれ順番に見ていきましょう。

agy：ターミナルから操作する中核コマンド

agy は、ユーザーがターミナルから直接操作するコアコマンドラインインターフェースです。

たとえば、次のような操作は agy コマンドを中心に行います。

エージェントに作業を依頼する
設定を変更する
スキルを確認する
実行ログを見る
タスクの実行結果を確認する

イメージとしては、Antigravity CLIを使うための入口です。

ブラウザを開いてAIに相談するのではなく、普段使っているターミナルからAIエージェントを呼び出せるのが特徴です。

Antigravity API：処理を振り分けるオーケストレーション層

Antigravity APIは、ローカルから送られた要求を解釈し、適切なLLMや外部リソースへ処理を振り分ける層です。

主に、次のような役割を担います。

認証
コンテキスト管理
モデルの選択
セキュリティポリシーの適用
外部リソースとの連携

CLIから見ると、agy run のようなシンプルな操作に見えます。

しかし裏側では、次のような判断が必要になります。

どのモデルを使うのか
どのファイルを参照するのか
どの権限で実行するのか
どのスキルを使えるようにするのか

この調整役になるのが、Antigravity APIです。

MCP：AIとローカル環境を安全につなぐ仕組み

MCPは、Model Context Protocolの略です。

AIモデルがローカルファイル、データベース、IDE、外部開発ツールなどへ安全にアクセスするためのコンテキストプロトコルです。

AIが文章を生成するだけなら、ローカル環境に深く接続する必要はありません。

しかし、実際の開発作業では話が変わります。

コードを読み、ファイルを書き換え、テストを実行し、ログを確認するには、AIと開発環境の間に安全な橋渡しが必要です。

MCPは、そのための規格として使われます。

Antigravity CLIでは、このMCPによって、AIエージェントがローカル環境を理解しながら作業できる設計になっています。

Google GeminiやClaudeのWeb UIとの違い

Google GeminiやClaudeのようなWeb UI型のAIサービスは、ブラウザ上で会話しながら使う形式です。

質問への回答、文章生成、コード例の提示などには非常に便利です。

ただし、実際にローカルのファイルを直接操作したり、複数のコマンドを組み合わせて自律的に作業したりするには、基本的にユーザー側の手作業が入ります。

一方で、Antigravity CLIは、ターミナルからAIエージェントに指示し、必要なスキルやMCP連携を通じて、より実行寄りの作業を進められる点が特徴です。

評価軸	Gemini / ClaudeなどのWeb UI	従来型のAI CLI	Antigravity CLI
操作場所	ブラウザ	ターミナル	ターミナル＋エージェント実行
コンテキスト理解	会話内容が中心	単一ファイルや履歴が中心	MCPによりローカル環境まで扱いやすい
自律実行	基本的に不可	限定的	スキルを組み合わせて実行しやすい
安全確認	ユーザーの手作業に依存	実装次第	confirmによる承認フローを組み込みやすい

結論として、Antigravity CLIは 「AIに聞く」よりも「AIに進めてもらう」ことに寄ったツール だと考えると理解しやすいです。

エージェント・スキル・Runの考え方

Antigravity CLIを使ううえで重要なのが、次の3つの考え方です。

エージェント
スキル
Run

この3つを押さえると、Antigravity CLIの全体像がかなり見えやすくなります。

エージェント

エージェントは、特定の役割を持ったAIです。

たとえば、次のような役割を与えられます。

コードレビュー担当
ドキュメント作成担当
データ抽出担当
テスト作成担当
設計チェック担当

単なる汎用AIではなく、目的に応じて振る舞いを決められる点が重要です。

つまり、エージェントは 「何でも屋」ではなく、役割を持った作業担当者 のような存在です。

スキル

スキルは、エージェントが実行できる具体的な機能です。

たとえば、次のようなものがスキルにあたります。

Git操作
ファイル読み書き
API呼び出し
メール下書き作成
ログ解析
データ集計

エージェントは、与えられたスキルの範囲内で作業します。

逆に言えば、不要なスキルを渡さなければ、エージェントにできる操作を制限できます。

これは安全面でもかなり重要です。

Run

Runは、エージェントとスキルを組み合わせて、1つのタスクとして実行する流れです。

たとえば、次のようなコマンドでエージェントに作業を依頼します。

agy run "Create a hello world text file" --confirm

このように、自然文の指示とオプションを組み合わせて、ターミナルからタスクを実行するのが基本です。

代表的なユースケース

Antigravity CLIでできることを具体的に考えると、次のような使い方があります。

コードレビューの自動化

agy run review

ステージングされたコードを確認し、脆弱性、設計上の問題、可読性の低い箇所などを検出して、修正案やパッチを作る使い方です。

MCP経由でローカルのリポジトリを参照できるため、単なる断片的なコードレビューではなく、プロジェクト全体の文脈を踏まえた確認 が期待できます。

環境構築の自動化

新規プロジェクトを作るときに、必要な依存ライブラリ、設定ファイル、ディレクトリ構成、初期コードなどをまとめて準備する使い方です。

毎回同じ設定を手作業で行うのは、地味に時間がかかります。

そのような作業をエージェントに任せることで、初期構築の負担を減らせます。

ドキュメント生成

コードの内容を読み取り、APIドキュメントやREADMEを生成する用途にも向いています。

agy run "Generate API documentation" --silent --output ./docs/api.md

このように、出力先を指定してドキュメント化する流れも考えられます。

導入前に確認したい環境・アカウント・権限

必要な環境

Antigravity CLIを使う前に、まずローカル環境を確認しておきましょう。

想定されるOSは、Windows、macOS、Linuxです。

Windowsでは、Windows 11に加えて、WSL2を使う構成が扱いやすいです。

もちろん、PowerShell上でネイティブに動かす方法もあります。

Pythonは、3.10以上を前提にすると安心です。

CLIツールや関連ライブラリをインストールする場合、グローバル環境に直接入れるよりも、venv などで仮想環境を分けたほうがトラブルを避けやすくなります。

ターミナルは、Windows Terminal、iTerm2、各種IDEの内蔵ターミナルなどが使えます。

VS CodeやCursorを使っている場合は、内蔵ターミナルで作業する流れが自然です。

推奨される準備物

Antigravity CLIを使い始める前に、次の要素を確認しておくと安心です。

OSとターミナル

Windows、macOS、Linuxのいずれかで作業します。

Windowsの場合は、PowerShellだけでなくWSL2も候補になります。

開発系CLIはLinuxベースのコマンドと相性がよいケースが多いため、WSL2を使える環境なら検討する価値があります。

Python環境

Python 3.10以上を用意します。

バージョン確認は、次のコマンドで行えます。

python --version

環境によっては、python3 を使う場合もあります。

python3 --version

ここで想定したバージョンが表示されれば、次へ進めます。

仮想環境

プロジェクトごとに環境を分けるため、仮想環境を作成します。

python -m venv .antigravity-env

macOSやLinuxでは、次のように有効化します。

source .antigravity-env/bin/activate

Windowsでは、次のように有効化します。

.antigravity-env\Scripts\activate

仮想環境を使うことで、他のPythonプロジェクトと依存関係が衝突しにくくなります。

CLI系のトラブルは、環境の混在が原因になることも多いです。

そのため、最初から仮想環境を使うのがおすすめです。

IDE

VS CodeやCursorなどのIDEを使うと、エディタとターミナルを同じ画面で扱えます。

MCP連携やスキーマ補完に対応する拡張機能を利用できる場合、Antigravity CLIとの相性も良くなります。

アカウント作成とAPIキー

Antigravity CLIを利用するには、管理コンソールでアカウントを作成し、APIキーを発行する流れが想定されます。

一般的な手順は、次のとおりです。

公式サイトまたは管理コンソールでアカウントを作成する
API Keysセクションを開く
新しいシークレットキーを発行する
ローカル環境の環境変数に登録する
CLIの初期設定時にAPIキーを指定する

APIキーは、パスワードと同じく機密情報です。

GitHubなどの公開リポジトリに誤ってコミットしないよう注意しましょう。

ここは本当に大事です。

APIキーの流出は、余計な課金や不正利用につながる可能性があります。

利用規約とセキュリティで確認したい点

AIエージェントにコードやファイルを扱わせる場合、事前に確認しておきたいポイントがあります。

データの取り扱い

入力したコード、プロンプト、ログ、ファイル内容が、モデルの再学習に使われるのかどうかは重要です。

商用プロジェクトや機密情報を含む開発では、オプトアウト設定やデータ保持ポリシーを確認しておく必要があります。

「便利だから使う」だけでなく、どの情報がどこまで送られるのか は必ず確認しておきましょう。

レート制限

無料枠や契約プランには、1分あたり、1日あたりのリクエスト上限が設けられていることがあります。

大量の自動処理やCI/CDへの組み込みを考えている場合、TPMやRPMのような制限を確認しておくと安心です。

制限を知らずに自動化すると、途中で処理が止まることもあります。

アクセス権限

組織アカウントで使う場合、どのユーザーがどのモデルやスキルを使えるのか、どのプロジェクトにアクセスできるのかを決める必要があります。

後から権限周りで詰まらないように、導入前に管理者設定を確認しておきましょう。

ローカル実行とCloudハイブリッドの違い

Antigravity CLIは、用途に応じてローカル中心の使い方と、クラウドを組み合わせる使い方が考えられます。

ローカル実行モード

ローカル実行モードでは、MCPサーバーやスクリプト実行を自分のPC上で完結させます。

メリットは、機密性の高いソースコードやファイルを外部に出すリスクを抑えやすい点です。

セキュリティ要件が厳しいプロジェクトでは、ローカル中心の構成が向いています。

また、通信を限定したい場合や、社内ネットワーク内で完結させたい場合にも選びやすい構成です。

Cloudハイブリッドモード

Cloudハイブリッドモードでは、重い推論処理や大規模な並列タスクをマネージドサーバー側へ委任します。

ローカルマシンの性能に左右されにくく、複数エージェントを使った大きなワークフローを動かしやすい点がメリットです。

チームでスキルやエージェント設定を共有したい場合にも、クラウド連携は便利です。

ただし、クラウドを使う場合は、データ送信範囲や権限設計をより慎重に確認しましょう。

インストールと初期設定：まずは動く状態にする

仮想環境を作成する

まずは作業用ディレクトリで仮想環境を作成します。

python -m venv .antigravity-env

macOSやLinuxでは、次のコマンドで有効化します。

source .antigravity-env/bin/activate

Windowsの場合は、次のように実行します。

.antigravity-env\Scripts\activate

仮想環境が有効になると、ターミナルの表示に環境名が出ることがあります。

これで、以降のインストール先がプロジェクト専用の環境になります。

Antigravity CLIをインストールする

本体は pip を使ってインストールします。

pip install --upgrade antigravity-cli

インストールが終わったら、agy コマンドが使えるか確認します。

agy --version

ここでバージョン情報が表示されれば、CLI本体は認識されています。

もし表示されない場合は、PATHや仮想環境の有効化を確認しましょう。

初期設定を行う

次に、対話型の初期設定を実行します。

agy setting --init

この初期設定では、次のような内容を登録する流れが想定されます。

APIキー
デフォルトで使うモデル
MCPサーバーの設定
エージェント設定
利用するスキルの設定

設定は後から変更できます。

最初の段階では、最小限の接続確認ができれば十分です。

最初から完璧に設定しようとしなくても大丈夫です。

Gemini連携用ライブラリを追加する

Antigravity CLIがGemini APIなどのLLMプロバイダをサポートしている場合、必要な追加ライブラリをインストールします。

pip install antigravity-cli[gemini]

モデルやプロバイダを切り替える場合は、設定ファイルや agy setting コマンドから指定します。

PATHの確認

インストール後に agy コマンドが認識されない場合、PythonのScriptsディレクトリがPATHに入っていない可能性があります。

Windowsの場合、次のようなパスが関係します。

%USERPROFILE%\AppData\Local\Programs\Python\Python3x\Scripts

仮想環境を使っている場合は、仮想環境を有効化してから agy を実行しているか確認します。

.antigravity-env\Scripts\activate
agy --version

macOSやLinuxでは、仮想環境を有効化した状態で次を確認します。

which agy

Windows PowerShellでは、次のように確認できます。

Get-Command agy

CLIが動かないときは、まず「どのPython環境で実行しているのか」を確認するのが近道です。

Hello Worldで動作確認する

最初の動作確認として、シンプルなファイル生成を試します。

agy run "Create a hello world text file" --confirm

このコマンドでは、エージェントに「Hello Worldのテキストファイルを作る」という作業を依頼します。

--confirm を付けているため、ファイルを書き込む前に確認が入ります。

AIエージェントにローカル環境を操作させる場合、最初は必ず承認フローを入れておくと安心です。

正常に動けば、カレントディレクトリに hello_world.txt のようなファイルが生成されます。

confirmを使う理由

AIエージェントにファイル操作やコマンド実行を任せるとき、重要なのは安全性です。

--confirm を付けることで、エージェントが実際に変更を加える前に、ユーザーが確認できます。

特に、次のような操作では承認フローを入れるべきです。

ファイルの作成・削除・上書き
設定ファイルの変更
外部APIへの送信
デプロイや本番環境に関係する操作
シェルコマンドの実行

慣れてきたとしても、本番環境に近い操作では確認を省略しないほうが安全です。

便利さに慣れた頃が、一番危ないです。

基本コマンドと実践的な使い方

よく使うコマンド

Antigravity CLIで日常的に使うコマンドは、いくつかに整理できます。

まずは、基本となるコマンドから押さえていきましょう。

agy run

最も重要なのが agy run です。

agy run "Review the latest changes"

自然文で指示を与え、エージェントにタスクを実行させます。

コードレビュー、ドキュメント生成、ファイル作成、設定変更、データ処理など、幅広い作業の入口になります。

Antigravity CLIを使うなら、まず覚えるべきコマンドです。

agy setting

設定を確認・変更するコマンドです。

agy setting

初期化する場合は、次のように使います。

agy setting --init

モデル、APIキー、MCPサーバー、デフォルトエージェント、スキル登録などの設定管理に使います。

設定まわりで迷ったら、まず agy setting を確認しましょう。

agy confirm

保留中のアクションを承認または却下するためのコマンドです。

agy confirm

エージェントが複数のファイル変更やコマンド実行を提案した場合、内容を確認してから進められます。

AIに任せるとはいえ、最終判断は人間側が持つべきです。

そのためにも、confirm の考え方はかなり重要です。

agy list / agy skills

利用可能なエージェントやスキルを確認します。

agy list

または、スキル一覧を確認します。

agy skills

現在どの機能が使えるのかを把握しておくと、エージェントに任せる範囲を決めやすくなります。

オプションの使い方

Antigravity CLIでは、オプションを組み合わせることで、実行時の挙動を細かく制御できます。

--confirm

変更前に確認を求めるオプションです。

agy run "Deploy standard monitoring config" --confirm

安全性を重視するなら、基本的に付けておきたいオプションです。

特に、ファイル変更やコマンド実行が関係する場合は、--confirm を使うのがおすすめです。

--env

実行環境を指定するオプションです。

agy run "Deploy standard monitoring config" --confirm --env production

--env production のように指定することで、本番環境用の設定や権限プロファイルを読み込ませる構成が考えられます。

ただし、本番環境での実行は特に慎重に扱う必要があります。

productionという文字が出た瞬間、確認の目を一段階強めるくらいでちょうどいいです。

--silent

出力を抑えて実行するオプションです。

agy run "Generate API documentation" --silent --output ./docs/api.md

CI/CDやスクリプトに組み込む場合、余計なログ出力を減らしたいことがあります。

そのようなときに便利です。

--output

成果物の出力先を指定します。

agy run "Generate API documentation" --output ./docs/api.md

ドキュメント、レポート、レビュー結果などをファイルとして残したい場合に使います。

あとから見返せる形で残せるので、レビューや共有にも向いています。

実行ログとアーティファクト

エージェントが生成した成果物は、アーティファクトとして扱われます。

デフォルトでは、プロジェクト内の .agy/artifacts/ にタイムスタンプ付きで保存される構成が想定されます。

.agy/
└── artifacts/
    ├── 2026-xx-xx-review-report.md
    └── 2026-xx-xx-generated-docs.md

実行結果をあとから確認したい場合や、エージェントがどのようなファイルを作ったのか追跡したい場合に役立ちます。

AIエージェントを使う場合、「何をしたか」が残っていることはかなり大切です。

ログを確認する

直近の実行ログを詳しく見る場合は、次のように実行します。

agy log --last --verbose

ログでは、次のような情報を確認できます。

エージェントがどのような判断をしたのか
どのファイルにアクセスしたのか
どのスキルを使ったのか
どのような出力を生成したのか

デバッグ時は、ログを確認することで原因を絞り込みやすくなります。

開発・自動化・拡張に活かす運用方法

プロジェクトの基本構成

Antigravity CLIをプロジェクトで使う場合、ディレクトリ構成を整理しておくと管理しやすくなります。

my-agy-project/
├── .agy/
│   ├── config.yaml
│   └── artifacts/
├── skills/
│   └── custom_tool.py
├── agents/
│   └── reviewer.json
├── src/
└── agy-requirements.txt

それぞれの役割を見ていきましょう。

.agy

.agy は、Antigravity CLIの管理領域です。

プロジェクト固有の設定や、生成されたアーティファクト、ログなどを置く場所として使われます。

設定や実行結果が散らばらないよう、ここで管理するイメージです。

skills

skills ディレクトリには、エージェントが利用できるカスタムスキルを置きます。

たとえば、次のような機能を定義できます。

ファイル操作
API連携
システム情報取得
データ加工
社内ツールとの連携

プロジェクトに合わせた機能を用意できるのがポイントです。

agents

agents ディレクトリには、カスタムエージェントの定義を置きます。

レビュー担当、テスト担当、ドキュメント担当など、役割別に設定を分けると運用しやすくなります。

役割が曖昧なエージェントを増やすよりも、責任範囲をはっきりさせたエージェントを作るほうが安定します。

src

src は開発対象のメインソースコードです。

エージェントにレビューや修正を依頼する場合、このディレクトリ内のコードを対象にすることが多くなります。

ローカル開発からテストまでの流れ

Antigravity CLIは、ローカル開発の補助として使いやすいです。

たとえば、次のような作業に使えます。

リファクタリング案を出してもらう
テストコードを生成してもらう
差分をレビューしてもらう
重複ロジックを見つけてもらう

たとえば、次のように依頼できます。

agy run "Refactor the duplicated logic in src and propose safe changes" --confirm

変更を伴う操作では --confirm を付けて、提案内容を確認してから反映します。

AIに丸投げするのではなく、提案を見てから採用するという流れが安全です。

統合テストで使う

MCPサーバーを介して、ステージング環境やテスト用データベースと接続し、統合テストを支援させる使い方も考えられます。

agy test --suite integration

ローカルのコードと外部環境の接続確認を行う場合、接続先や認証情報を明確に分けておくことが重要です。

本番環境とテスト環境の設定が混ざると、思わぬ事故につながります。

デプロイに組み込む

ローカルで検証したスキルやエージェント構成を、クラウド環境や共有サーバーにデプロイする流れも考えられます。

agy deploy --target cloud

チームで同じエージェント設定を使いたい場合や、CI/CDから呼び出したい場合には、共有環境への反映が便利です。

ただし、共有環境に反映する前には、必ず権限やログの取り扱いを確認しておきましょう。

CI/CDに組み込む例

GitHub ActionsなどのCI/CDにAntigravity CLIを組み込むと、コードがプッシュされたタイミングでAIエージェントによるレビューやドキュメント更新を実行できます。

- name: Run Antigravity Autonomous Review
  env:
    ANTIGRAVITY_API_KEY: ${{ secrets.ANTIGRAVITY_API_KEY }}
  run: |
    pip install antigravity-cli
    agy run "Review the structural changes in the latest commit and output a summary" --silent > review_report.md

このように設定すれば、プルリクエストごとに構造変更の要約やレビュー結果を自動生成する流れを作れます。

ただし、CI環境で使うAPIキーは必ずSecretsに保存しましょう。

ログにAPIキーが出力されないようにすることも重要です。

APIを直接使う

CLIだけでなく、PythonスクリプトからAntigravityの機能を呼び出す構成も考えられます。

import os
from antigravity import AntigravityClient

client = AntigravityClient(api_key=os.environ.get("ANTIGRAVITY_API_KEY"))

response = client.agents.execute(
    agent_id="code-optimizer",
    prompt="Optimize the loop efficiency in the attached snippet.",
    context_files=["./src/utils.py"]
)

print("Agent Response:", response.text)

このようにAPIを使うと、独自の業務ツールや社内システムにAntigravityのエージェント機能を組み込めます。

CLIだけで完結させるよりも、より柔軟な自動化がしやすくなります。

外部サービスとの連携

Antigravity CLIは、MCPを通じて外部サービスや開発ツールと連携する構成を取りやすいです。

GeminiやClaudeとの連携

設定ファイルでプロバイダを切り替えることで、タスクに応じて使うモデルを変える設計ができます。

provider: gemini

または、次のように指定します。

provider: claude

コード生成、設計レビュー、長文の要約、軽量なテキスト処理など、タスクごとにモデルを選び分けると効率的です。

すべてを高性能モデルに任せるより、作業内容に応じて使い分けるほうが現実的です。

Chrome拡張との連携

ブラウザで表示しているエラー画面やドキュメントを、MCP経由でCLI側に渡すような連携も考えられます。

たとえば、Webページで見ているAPIドキュメントをもとに、ローカルのコード修正案を作るといった流れです。

ブラウザとターミナルをつなげられると、調査から実装までの流れがかなりスムーズになります。

カスタムスキルを作る

Antigravity CLIでは、Python関数としてスキルを定義する構成が想定されます。

from antigravity.skills import skill

@skill(name="fetch_system_load", description="ローカルマシンのCPUおよびメモリ使用率を取得します")
def fetch_system_load() -> dict:
    import psutil
    return {
        "cpu": psutil.cpu_percent(interval=1),
        "memory": psutil.virtual_memory().percent
    }

このスキルでは、CPU使用率とメモリ使用率を取得して返します。

登録する場合は、次のようなコマンドを使います。

agy setting --register-skill skills/custom_tool.py

カスタムスキルを使えば、自分の作業環境に合わせてAntigravity CLIを拡張できます。

権限設計を行う

カスタムスキルを作るときは、便利さだけでなく権限設計も重要です。

スキルごとに、読み取り、書き込み、実行といった権限を分けることで、エージェントが必要以上の操作をしないようにできます。

たとえば、ログを読むだけのスキルにファイル削除権限は不要です。

データ集計スキルにシェル実行権限を与える必要もありません。

最小限の権限で動かすことが、AIエージェントを安全に使う基本です。

ここを雑にすると、便利なはずの自動化がリスクに変わります。

日常タスクの自動化

Antigravity CLIは、開発以外の日常的な業務自動化にも応用できます。

たとえば、次のような流れです。

複数のCSVファイルを読み込む
月別に売上を集計する
Markdown形式の報告書を作成する
メールの下書きを作る

コマンド例は、次のとおりです。

agy run "集計タスクフローの実行" \
  --instruction "1. ./data 内の全CSVを読込 / 2. 売上を月別集計 / 3. report.md に出力 / 4. 下書きメール作成" \
  --allow-skills "file_io,gmail_draft"

この例では、使えるスキルを file_io と gmail_draft に限定しています。

エージェントに作業を任せる場合、すべての権限を渡すのではなく、必要なスキルだけ許可するのが安全です。

複数エージェントの連携

複雑な開発作業では、1つのエージェントだけでなく、複数のエージェントを組み合わせる方法があります。

たとえば、次のような役割分担です。

Plannerエージェント

全体のタスクを分解し、作業順序を決めます。

いきなり作業に入るのではなく、まず計画を立てる役割です。

Workerエージェント

実際にコードを書いたり、ファイルを生成したりします。

バックエンド担当、フロントエンド担当、テスト担当のように分けることもできます。

Reviewerエージェント

成果物を確認し、問題点や不整合を見つけます。

作る人と確認する人を分けることで、品質を保ちやすくなります。

このような流れは、Flowとして定義して実行できます。

agy flow run ./flows/dev_pipeline.json

複数エージェントを使う場合は、役割の重複を避け、各エージェントの責任範囲を明確にすることが大切です。

プロンプト設計のコツ

エージェントに指示を出すときは、曖昧な依頼よりも、構造化された指示のほうが安定します。

たとえば、次の要素を入れると分かりやすくなります。

目的
前提条件
変更してよい範囲
変更してはいけない範囲
出力形式
確認すべき観点

例として、コードレビューを依頼するなら次のように書けます。

agy run "Review src for security, readability, and duplicated logic. Do not modify files. Output findings as markdown." --confirm

この指示では、次の点が明確です。

src をレビュー対象にする
セキュリティ、可読性、重複ロジックを見る
ファイルは変更しない
Markdown形式で出力する

「ファイルを変更しない」「Markdownで出力する」と明示することで、期待する結果に近づけやすくなります。

モデル選択の考え方

タスクによって、使うモデルを変える考え方も重要です。

複雑なコード生成や設計判断では、高い推論力と広いコンテキストウィンドウを持つモデルが向いています。

一方、単純なテキスト分類、ログ抽出、軽い整形処理などでは、軽量で低コストなモデルを使うほうが効率的です。

すべての作業を高性能モデルに任せる必要はありません。

タスクの難易度に応じて使い分けることで、コストと速度のバランスを取りやすくなります。

トラブルシューティングと安全に使うための考え方

MCPサーバーのポート競合

MCPサーバー起動時に、次のようなエラーが出ることがあります。

EADDRINUSE: port xxxx already in use

これは、指定されたポートがすでに別のプロセスに使われている状態です。

Vite、Docker、ローカル開発サーバーなどが同じポートを使っている可能性があります。

Windows PowerShellでは、次のように該当プロセスを確認して停止できます。

Get-Process -Id (Get-NetTCPConnection -LocalPort <ポート番号>).OwningProcess | Stop-Process

または、Antigravity CLI側の設定でMCPサーバーのポート番号を変更します。

agy setting

設定から競合しないポートへ変更すれば、起動できるようになります。

ポート競合はよくあるエラーなので、焦らず確認しましょう。

ModuleNotFoundErrorが出る場合

次のようなエラーが出ることがあります。

ModuleNotFoundError: No module named 'antigravity'

この場合、Antigravity CLIをインストールしたPython環境と、現在実行しているPython環境が違っている可能性があります。

まず、仮想環境が有効化されているか確認します。

source .antigravity-env/bin/activate

Windowsでは、次のように実行します。

.antigravity-env\Scripts\activate

そのうえで、再度インストールします。

pip install antigravity-cli

Python環境のズレは、CLIツール導入時によく起きる問題です。

which python や which agy、Windowsなら Get-Command を使って、どの実行ファイルが使われているか確認すると原因を見つけやすくなります。

APIキーの認証エラー

APIキーが正しく設定されていない場合、認証エラーが出ます。

まず、環境変数にキーが入っているか確認します。

macOSやLinuxでは、次のように確認します。

echo $ANTIGRAVITY_API_KEY

Windows PowerShellでは、次のように確認します。

echo $env:ANTIGRAVITY_API_KEY

認証テスト用のコマンドが用意されている場合は、次のように確認します。

agy confirm --auth-test

APIキーの設定ミスは、コピー漏れや余計な空白が原因になることもあります。

一度落ち着いて見直しましょう。

401 Unauthorized

401 Unauthorized は、APIキーが間違っている、期限切れになっている、または無効化されている場合に出ることがあります。

確認したいポイントは、次のとおりです。

キーのコピー漏れがないか
余計な空白が入っていないか
古いキーを使っていないか
管理画面でキーが無効化されていないか

認証まわりは、まずキーの状態を確認するのが基本です。

403 Forbidden

403 Forbidden は、認証は通っているものの、権限が不足している場合に出ることがあります。

確認したいポイントは、次のとおりです。

組織設定
IAMロール
利用可能なモデル
スキル実行権限
プロジェクトへのアクセス権限

特にチーム利用では、個人アカウントでは動くのにCI環境では動かない、といったケースがあります。

その場合は、CI用のAPIキーに必要な権限が付いているか確認しましょう。

実行時の挙動がおかしい場合

エージェントが意図した通りに動かない場合は、デバッグログを出します。

agy run "対象のタスク" --debug --log-level=DEBUG

ログファイルは、次のような場所に保存される構成が考えられます。

.agy/logs/latest.log

ログ内では、特に次のようなセクションを確認します。

[MCP-REQUEST]
[MCP-RESPONSE]

ここを見ると、AIモデルがどのような引数をローカルツールへ渡したのか、MCP側がどのように応答したのかを確認できます。

エージェントの挙動がおかしいときは、感覚で直すよりログを見たほうが早いです。

安全に使うための原則

Antigravity CLIのように、AIエージェントがローカル環境にアクセスできるツールでは、安全性を最初から設計に入れておく必要があります。

便利なツールほど、権限を雑に扱うと危険です。

管理者権限で実行しない

ローカルPC上で実行する場合でも、Administratorやroot権限でCLIを動かすのは避けます。

必要以上に強い権限で動かすと、誤操作や想定外の挙動が起きたときの影響範囲が広がります。

基本は、通常ユーザー権限で十分です。

プロジェクトフォルダに限定する

エージェントがアクセスできる範囲は、できるだけプロジェクトフォルダ内に限定します。

ホームディレクトリ全体やシステム領域にアクセスできる状態は避けるべきです。

AIエージェントに触らせる場所は、明確に絞りましょう。

confirmを使う

ファイル変更、コマンド実行、外部送信、デプロイに関係する操作では、--confirm を使って確認を入れます。

特に、削除や上書きが発生する可能性がある操作では必須に近い扱いで考えます。

確認を省いた自動化は、速いぶんだけ危険も増えます。

ログを監査する

.agy/logs/ に記録されるログを確認し、どのファイルが変更されたか、どの外部通信が行われたかを追跡します。

組織利用では、中央ログ監視サーバーやSIEMに転送し、予期しないデータ送信がないか監査する運用も考えられます。

AIエージェントの作業は、あとから追える状態にしておきましょう。

ライセンスを確認する

AIが生成したコードを商用プロジェクトで使う場合、既存のオープンソースコードと類似していないか、ライセンス上の問題がないかを確認します。

GPLなどの強いコピーレフトライセンスに関係するコードが混入しないよう、ライセンススキャンをパイプラインに組み込むと安心です。

生成コードだからといって、無条件で安全とは限りません。

プラグインや拡張機能を作る場合

Antigravity CLIの機能を社内やチームで共有したい場合、プラグインとして拡張する方法があります。

agy plugin init my-extension

プラグインでは、package.json や plugin.yaml にメタデータ、MCPスキーマのバージョン、必要な権限などを定義します。

公開前には、次の確認を行うべきです。

静的コード解析
権限監査
サンドボックス内での実行確認
不要な外部通信の有無
APIキーや認証情報の扱い

便利なプラグインほど、強い権限を要求しがちです。

だからこそ、公開や共有の前に、何ができるプラグインなのかを明確にしておきましょう。

IDEやLintの設定

カスタムスキルやエージェント設定を長く運用するなら、開発環境の整備も重要です。

Pythonでスキルを書く場合は、Type Hintsを付けます。

def fetch_system_load() -> dict:
    ...

型が明確だと、エージェントが関数の入出力を誤解しにくくなります。

MyPyやRuffなどのLint、Formatterを組み合わせると、スキルコードの品質を保ちやすくなります。

VS CodeやCursorを使う場合は、MCPスキーマ定義を設定しておくと、自動補完や設定ミスの検出に役立ちます。

長く使うなら、最初から整った開発環境を作っておくのがおすすめです。

おわりに

Antigravity CLIは、AIをターミナルから使うだけの道具ではありません。

エージェント、スキル、MCPを組み合わせて、開発作業や運用作業を 実行に近い形で支援する仕組み として捉えると理解しやすいです。

まずは、次の流れで小さく試してみるのが現実的です。

仮想環境を作る
CLIをインストールする
agy setting --init で初期設定を行う
agy run と --confirm を使って小さな作業から試す

その後、コードレビュー、ドキュメント生成、CI/CD、自動化、カスタムスキル、複数エージェント連携へと広げていけば、活用範囲は大きく広がります。

ただし、AIエージェントにローカル環境を操作させる以上、次の点は欠かせません。

権限管理
ログ監査
APIキー管理
ライセンス確認
confirmによる事前確認

Antigravity CLIは便利な一方で、扱い方を間違えるとリスクもあります。

だからこそ、便利さと安全性のバランスを取りながら、小さく試して段階的に導入していくこと が大切です。

よくある質問

Q1. Antigravity CLIは何をするためのツールですか？

Antigravity CLIは、ターミナルからAIエージェントに作業を依頼し、コードレビュー、ファイル生成、ドキュメント作成、自動化、外部ツール連携などを行うためのCLIツールです。

AIチャットのように回答を受け取るだけではなく、MCPやスキルを通じて実際の開発環境と連携できる点が特徴です。

Q2. 最初に覚えるべきコマンドは何ですか？

まずは agy run、agy setting、agy confirm を押さえると使い始めやすいです。

agy run はタスク実行、agy setting は設定確認や初期化、agy confirm は実行前の承認に使います。

特にファイル変更を伴う操作では、--confirm を付けて安全確認を入れるのがおすすめです。

Q3. Windowsでも使えますか？

Windowsでも利用できます。

Windows 11の場合、PowerShellで使う方法とWSL2上で使う方法があります。

開発系CLIとの相性を考えると、WSL2を使う構成も検討しやすいです。

agy コマンドが認識されない場合は、PythonのScriptsディレクトリがPATHに入っているか、仮想環境が有効化されているかを確認しましょう。

Q4. APIキーはどこに保存すればよいですか？

APIキーは、環境変数や安全なシークレット管理機能に保存します。

ローカルでは ANTIGRAVITY_API_KEY のような環境変数に設定し、CI/CDではGitHub Actions Secretsなどを使います。

ソースコードや公開リポジトリに直接書き込むのは避けるべきです。

Q5. 安全に使うために一番重要なことは何ですか？

一番重要なのは、最小権限で使うことです。

エージェントに不要なファイルアクセス権限やコマンド実行権限を与えず、変更前には --confirm で確認します。

また、ログを確認し、APIキーを適切に管理し、生成されたコードのライセンスやセキュリティもチェックすることが重要です。