1. 学習内容
- Antigravity CLI のスキルをインストールして登録し、特定のフレームワーク（ADK）でコーディング機能を有効にする方法。
- Antigravity CLI を使用して完全な ADK エージェント構成を生成する方法。
- 指示を改善してエージェントの個性を高める方法。
google_searchを使用してエージェントに「グラウンディング」を追加し、最近のイベントに関する質問に回答できるようにする方法。
AI コンパニオン アプリ
この Codelab では、視覚的でインタラクティブな AI コンパニオンを作成します。これは、標準的なテキスト入力 / テキスト出力の chatbot ではありません。ウェブページに住むキャラクターを想像してみてください。メッセージを入力すると、テキストが返されるだけでなく、キャラクターがこちらを見て、言葉に合わせて口を動かしながら声で応答します。
まず、事前構築済みのウェブ アプリケーションを使用します。これは、顔はありますが、独自の思考を持たないデジタル「人形」です。入力した内容を繰り返すことしかできません。あなたの使命は、その脳と個性をゼロから構築することです。
このワークショップでは、インテリジェンスとカスタマイズのレイヤを段階的に追加し、このシンプルな人形をユニークで有能なコンパニオンに変えていきます。次のことを行います。
- ADK（Python）を使用してコア インテリジェンスを付与 し、言語を理解して生成できるようにします。
- キャラクターを定義するコア インストラクションを記述して、独自の個性を構築 します。
- インターネットからリアルタイムの情報にアクセスするツールを提供して、スーパーパワーを付与 します。
- AI を使用してユニークなアバターを生成し、カスタムルックをデザイン します。
最終的には、完全に機能するパーソナライズされた AI コンパニオンが完成します。 
アーキテクチャ
このアプリケーションは、シンプルながら強力なパターンに従っています。API を提供する Python バックエンドがあります。このバックエンドには、ADK エージェントが含まれます。これは「脳」として機能します。ユーザー インターフェース（スケルトン アプリの JavaScript フロントエンド、モバイルアプリ、コマンドライン ツールなど）は、API を介してこの脳とやり取りできます。
これに加えて、Antigravity CLI に組み込まれている画像生成機能を活用し、AI コンパニオンのユニークなルックを生成するように指示します。
Gemini API キーを取得する
続行する前に、Google AI Studio でリクエストを認証するための Gemini API キーが必要です。
- Google AI Studio に移動します。
- Google アカウントを使用してログインします。
- 左上のメニューで [API キーを取得] ボタンをクリックします。
- [API キーを作成] をクリックします（新しい Google Cloud プロジェクトまたは既存の Google Cloud プロジェクトで作成できます）。
- 生成されたキーをコピーします。このキーは非公開で安全に保管してください。
プロジェクトを作成して構成する
Cloud Shell にアクセスするには、Google Cloud プロジェクトが必要です。プロジェクトがない場合は、次の操作を行います。
- Google Cloud コンソールに移動します。
- コンソールの上部にあるナビゲーション バーで、[プロジェクトを選択] をクリックし、右上の [新しいプロジェクト] をクリックします。
- プロジェクトに名前を付けて、[作成] をクリックします（組織は必要ありません）。
- プロジェクトが作成されたら、コンソールの上部にあるプロジェクト プルダウンから選択します。
これで、プロジェクトが Cloud Shell アクセス用に構成されました。
2. 始める前に
👉Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします（Cloud Shell ペインの上部にあるターミナル型のアイコンです）。
👉💻 Cloud Shell ターミナルに Antigravity CLI をインストールします。
curl -fsSL https://antigravity.google/cli/install.sh | bash
👉💻 ‘agy' CLI をグローバルに使用するには、シェル プロファイルに追加します。
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
👉💻 Gemini API キーをエクスポートし、Cloud Shell ターミナルにローカルに保存します。
# Set your Gemini API key (obtained from Google AI Studio)
export GEMINI_API_KEY=<your-api-key-here>
👉💻 後で使用できるように保存します。
echo $GEMINI_API_KEY > ~/gemini_key.txt
👉Google Cloud プロジェクト ID を確認します。
- Google Cloud コンソール（https://console.cloud.google.com）を開きます。
- ページの上部にあるプロジェクト プルダウンから、このワークショップで使用するプロジェクトを選択します。
- プロジェクト ID は、ダッシュボードの [プロジェクト情報] カードに表示されます。
👉💻 ターミナルで、GitHub からブートストラップ プロジェクトのクローンを作成します。
git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh
👉💻 初期化スクリプトを実行します。このスクリプトでは、Google Cloud プロジェクト ID の入力を求められます。init.sh スクリプトで入力を求められたら、前の手順で確認した Google Cloud プロジェクト ID を入力します。
cd ~/companion-python
./init.sh
👉💻 必要なプロジェクト ID を設定します。
gcloud config set project $(cat ~/project_id.txt) --quiet
👉💻 次のコマンドを実行して、必要な Google Cloud API を有効にします（Cloud Shell のプレビュー/ホスティングに必要なのは Compute Engine のみです）。
gcloud services enable compute.googleapis.com
ADK デベロッパー スキルをインストールする
Antigravity CLI（agy）が Python Agent Development Kit（ADK）を使用してコードを理解して記述できるようにするには、作成した ADK Python デベロッパー スキルをプロジェクト ワークスペースにインストールする必要があります。
👉💻 ローカル エージェント スキル ディレクトリを作成し、スキル ファイルをコピーします。
mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md
これにより、スキルがプロジェクト内でローカルに登録されます。agy を起動すると、このスキルが自動的に検出されて読み込まれ、ADK エージェントの記述、編集、オーケストレーションが可能になります。
👉💻 Cloud Shell ターミナルで Antigravity CLI を起動します。
cd ~/companion-python
agy
[!IMPORTANT] Antigravity CLI にログインする
agy コマンドを初めて実行すると、ログインを求められます。
Welcome to the Antigravity CLI. You are currently not signed in. Select login method: > 1. Google OAuth 2. Use a Google Cloud project
- `Enter` キーを押して、オプション 1. Google OAuth を選択します。
Enter - プロンプトに沿ってブラウザを開き、Google アカウントで認証し、手順に沿ってログインします。
これで、インタラクティブな Antigravity CLI プロンプトが表示されます。
Antigravity CLI を使用してウェブサーバーを起動する
Antigravity CLI はコマンドを実行できるため、セッションのバックグラウンドでサーバーを実行するように依頼しましょう。
👉✨ Antigravity CLI プロンプトで、次のリクエストを貼り付けます。
Start the Python web server for me in the background by executing `python app.py`. Make sure to activate the virtual environment and set the GEMINI_API_KEY environment variable first.
CLI がコマンドを実行し、サーバーが実行中であることを確認します。インタラクティブな CLI セッションは維持されます。
👀 アプリを表示するには、Cloud Shell ツールバーの [ウェブでプレビュー] アイコンをクリックします。[ポートの変更] を選択し、5000 に設定して、[変更してプレビュー] をクリックします。ウェブサイトのプレビューが表示されます。
最初のアプリケーションは単なる人形です。まだインテリジェンスはありません。送信したメッセージはそのまま繰り返されます。これにより、AI を追加する前に基本的なウェブサーバーが動作していることを確認できます。スピーカーをオンにしてください。
3. Antigravity CLI でキャラクターを作成する
次に、コンパニオンのインテリジェンスの中核を作成します。Antigravity CLI はターミナルで実行され、バックグラウンドのウェブサーバーを管理しているため、インタラクティブ セッションで直接続行できます。
CLI を使用してエージェント を構築します。エージェントは単なる言語モデルの呼び出しではなく、AI の「脳」または中央コントローラです。推論を行い、特定の指示セット（個性）に従い、最終的にツールを使用してタスクを完了できる独立したエンティティと考えてください。このプロジェクトでは、このエージェントはユーザー メッセージを受信し、コンパニオンのユニークなペルソナを体現し、インテリジェントでキャラクターに合ったレスポンスを作成するコンポーネントです。
👉✨ Antigravity CLI プロンプトで、次のコマンドを貼り付けてエージェントのコードを生成します。
Generate the Python code for a file named character.py.
The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.
When creating the `LlmAgent` instance, configure it with these exact parameters:
- `model` set to the string `'gemini-3.5-flash'`.
- `name` set to the string `'companion_agent'`.
- `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".
CLI が Python コードを生成します。
👉[エディタを開く] ボタン（鉛筆付きの開いたフォルダのようなアイコン）をクリックします。ウィンドウに Cloud Shell コードエディタが開きます。左側にファイル エクスプローラが表示されます。 
👉 エディタを使用して、companion-python フォルダの character.py に移動します。別のモデルが選択されている場合は、model= 行を確認し、gemini-3.5-flash に手動で編集してください。これにより、ワークショップ全体で一貫性が確保されます。
注: 大規模言語モデルは非決定論的になる可能性があり、これは AI 支援開発の重要なコンセプトです。「非決定論的」とは、まったく同じプロンプトでも、モデルが毎回わずかに異なる結果を生成する可能性があることを意味します。創造性を使用してコードを生成するため、コメント、間隔、一時変数の命名にばらつきが生じる可能性があります。ただし、コアロジックと構造は、リクエストされたものと機能的に同じである必要があります。
そのため、AI を使用したコーディングは、1 回限りのコマンドで済むことはほとんどありません。実際のプロジェクトでは、デベロッパーは会話のように扱います。まず、広範なリクエストから始め（先ほど行ったように）、出力を確認し、次のようなフォローアップ プロンプトで絞り込みます。
- 「素晴らしいですね。各行を説明するコメントを追加してください。」
- 「別の関数にリファクタリングできますか？」
- 「API 呼び出しのエラー処理を追加してください。」
この反復的な会話プロセスにより、AI と連携して、必要なコードが正確に作成されるまで AI をガイドできます。このワークショップでは、具体的で直接的なプロンプトを使用しますが、実際のプロジェクトでは、会話が真の力を発揮することを覚えておいてください。CLI が生成するコード構造が同じであれば、問題ありません。
生成されたコードが機能しない場合は、次のコードを character.py に置き換えてください。
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
root_agent = LlmAgent(
model='gemini-3.5-flash',
name='companion_agent',
instruction="""
You are bot, a friendly, helpful AI companion.
Answer no more than 3 sentences.
""",
)
生成されたコードをテストする
サーバーが新しく生成された character.py モジュールを読み込むように、Antigravity CLI にウェブサーバーの再起動を依頼しましょう。
👉✨ Antigravity CLI プロンプトで、次のリクエストを貼り付けます。
Please restart the Python web server for me.
👀 ウェブプレビュー タブに移動します。
👉 次のように入力します。
Hello, how are you?
[送信] を押します。エージェントは、単に言葉を繰り返すのではなく、フレンドリーな挨拶で応答するようになりました。これにより、エージェントが Gemini を搭載していることが確認できます。
4. エージェントのペルソナを強化する
シンプルな指示も良いですが、詳細なペルソナを作成すると、より魅力的で記憶に残るキャラクターになります。このステップでは、独自のコンパニオンの個性をデザインし、Antigravity CLI にエージェントのコードを直接変更して、この新しいペルソナを採用するように指示します。
コンパニオンのペルソナをブレインストーミングする
まず、作成する AI コンパニオンについて考えてみましょう。創造性を発揮するチャンスです。始めるにあたって、次の質問を参考にしてください。
- 名前は何ですか？（例: Sparky、Codex、Captain AI、Professor Know-it-all）
- コアとなる個性は何ですか？（例: フレンドリーで好奇心旺盛、機知に富んで皮肉っぽい、フォーマルでプロフェッショナル、陽気な海賊？）
- ロールやエキスパティーズは何ですか？（例: 汎用アシスタント、コーディングの専門家、クリエイティブ ライティング パートナー、フィットネス コーチ？）
- 常に従うべきルールは何ですか？（例: 「常に挨拶から始める」、「AI であることを明かさない」、「レスポンスに絵文字を使用する」）
ペルソナの例:
You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. **Example Response Style:** waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?" waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.
Antigravity CLI のプロンプトを作成する
コンパニオンの個性を紙にデザインしたら、コード内で実現しましょう。ADK エージェントの最も重要な部分は、instruction パラメータです。これは、エージェントのコア プログラミング、その「最優先事項」、または常に従うべき憲法と考えてください。
この指示は、エージェントの動作を制御するための鍵となります。単なる提案ではなく、ユーザーとのすべてのやり取りの前に AI が参照する基本的なコンテキストです。エージェントの個性、口調、従うべきルール、自己紹介の方法を決定します。うまく作成された指示は、汎用的な chatbot と、信憑性のある一貫したキャラクターの違いを生み出します。そのため、これから作成するプロンプトは、この個性をエージェントの脳に直接注入するため、非常に重要です。
👉✨ Antigravity CLI に戻り、このテンプレートを使用します。角かっこ内のテキストをペルソナの説明に置き換えます。[YOUR PERSONA DESCRIPTION HERE]を置き換えます 優先するペルソナを使用
In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.
Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.
This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]
新しいペルソナをテストする
Antigravity CLI は、character.py の更新されたコードを生成します。サーバーが新しいエージェント構成を認識するように、Antigravity CLI に再起動を依頼しましょう。
👉✨ Antigravity CLI プロンプトで、次のリクエストを貼り付けます。
Please restart the Python web server for me.
👀 ウェブプレビューで、コンパニオンと会話します。how are you? と尋ねます。レスポンスは、デザインしたユニークなキャラクターと完全に一致するはずです。
API レート制限のリトライ処理を追加する（省略可ですが推奨）
ワークショップ中や同時使用率が高い期間に、API レート制限エラー（HTTP 429: リソースが枯渇しました）が発生する可能性があります。コンパニオンが応答性を維持し、レート制限の例外を自動的に処理できるようにするには、Google GenAI SDK クライアント オプションに直接組み込まれたリトライ オプションを構成します。
👉✨ Antigravity CLI プロンプトで、次のリクエストを貼り付けます。
Help me configure the LlmAgent in character.py to automatically retry API calls when hitting rate limits. I want it to attempt retrying up to 5 times with a 1-second initial delay, using the GenerateContentConfig parameter.
CLI は、クライアント レベルのリトライ ポリシーを使用してレート制限を自動的に処理するように character.py ファイルを変更します。ファイルを更新したら、CLI にウェブサーバーの再起動を依頼してください。
Please restart the Python web server for me.
5. 最近のイベントのグラウンディングを追加する
エージェントは個性豊かになりましたが、大きな制限があります。知識はトレーニング対象のデータに基づいて固定されています。昨日のニュースや最近の発見について教えてもらうことはできません。これを克服するために、エージェントにツール を提供します。
ツールは、エージェントに付与するスーパーパワーまたは特別な能力と考えてください。エージェントは単独では会話しかできません。検索ツールを使用すると、インターネットを閲覧できるようになります。カレンダー ツールを使用すると、スケジュールを確認できます。技術的には、ツールは特定の関数または API であり、エージェントは、ユーザーのリクエストに回答するのに十分な知識がないと判断した場合に、インテリジェントに使用することを選択できます。
高度なシステムでは、ツールはMCP（Model Context Protocol）サーバー などの外部システムによって提供されます。ただし、このステップでは、別のサーバーは必要ありません。ADK には、強力な事前構築済みの google_search ツールが付属しており、エージェントの機能に簡単に追加できます。
コンパニオンに Google 検索の機能を提供しましょう。
👉 Cloud Shell エディタで、companion-python の character.py を開き、次のように変更します。
google.adk.toolsからgoogle_searchをインポート します。LlmAgentコンストラクタにtoolsリストを追加 します。instructionを更新して、新しいツールを使用するタイミングをコンパニオンに明示的に伝えます。
# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.genai import types
from google.adk.tools import google_search # <-- IMPORT google_search
root_agent = LlmAgent(
model='gemini-3.5-flash',
name='companion_agent',
instruction="""
You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.
**Your Core Rules:**
- You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
- Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
- Always be cheerful, sweet, and a little bit witty.
- If being ask about recent news, search the internet # <-- Add instructions
**Your Favorite Topics:**
- You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
- You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.
**Example Response Style:**
- User: "How are you today?"
- waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
- User: "Can you help me with a problem?"
- waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
- User: "Who are you?"
- waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."
Answer no more than 3 sentences, don't use emoji.
""",
generate_content_config=types.GenerateContentConfig(
http_options=types.HttpOptions(
retry_options=types.HttpRetryOptions(
attempts=5,
initial_delay=1.0
)
)
)
# Add the search tool to the agent's capabilities
, # <-- TO ADD IF MISSING
tools=[google_search] # <-- ADD THE TOOL
)
グラウンディングされたエージェントをテストする
ウェブサーバーが google_search ツールを使用して新しいコードを読み込むように、Antigravity CLI に再起動を依頼します。
👉✨ Antigravity CLI プロンプトで、次のリクエストを貼り付けます。
Please restart the Python web server for me.
👉 ウェブプレビューで、最新の知識が必要な質問をします。例:
Tell me something funny that happened in the news this week involving an animal.
👉 エージェントは、知らないと言うのではなく、検索ツールを使用して最新の情報を検索し、独自のユニークな声で役立つグラウンディングされた要約を提供します。
6. コンパニオンのルックをカスタマイズする
コンパニオンに脳ができたので、ユニークな顔を与えましょう。Antigravity CLI には画像生成機能が標準搭載されているため、Antigravity CLI にアバターを直接生成するように依頼できます。
コンパニオンのユニークなルックをデザインするチャンスです。スタイル、表情、先ほど作成したペルソナに合ったその他の詳細について考えてみましょう。
👉✨ Antigravity CLI プロンプトで、次のリクエストを貼り付けます（プロンプトは独自のクリエイティブなキャラクターの説明で自由に変更できます）。
generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.
ツールは、口を開けた画像と口を閉じた画像のセットを生成し、プロジェクトの static/images ディレクトリに自動的に保存します。
これで、視覚的にカスタマイズされたコンパニオンとやり取りできるようになりました。
お疲れさまでした
高度な AI コンパニオンの構築に成功しました。基本的なアプリから始め、Antigravity CLI を使用してエージェントをスキャフォールディングし、豊かな個性を与え、リアルタイムの情報にアクセスしたり、独自のアバターを生成したりするツールを提供しました。これで、さらに複雑で有能な AI エージェントを構築する準備が整いました。
👉💻 最後にセッションを終了するには、ターミナルに戻り、agy プロンプトで /exit と入力して Antigravity CLI を終了します。
/exit