Antigravity CLI 和 ADK 初學者研討會 (建構您的第一個 AI 夥伴)

1. 學習內容

• 如何安裝及註冊 Antigravity CLI 的技能，以便在特定框架 (ADK) 中啟用程式設計功能。
• 如何使用 Antigravity CLI 生成完整的 ADK 代理設定。
• 如何改善指令，強化代理的個性。
• 如何為代理程式新增「基礎」，讓代理程式google_search回答近期活動相關問題。

AI Companion 應用程式

在本程式碼研究室中，您將打造生動活潑的互動式 AI 夥伴。這不只是標準的文字輸入/輸出聊天機器人，想像一下，網頁上住著一個角色。你輸入訊息後，角色會看著你並大聲回覆，嘴巴還會隨著說出的話移動，而不只是顯示文字回覆。

您會先使用預先建構的網頁應用程式，也就是沒有自己想法的數位「傀儡」。只能重複你輸入的內容。你的任務是從頭開始建構機器人的腦部和個性。

在研討會中，您將逐步加入智慧和自訂層，將這個簡單的木偶變成獨一無二的得力助手。您將：

• 使用 ADK(Python) 賦予核心智慧，讓代理程式瞭解及生成語言。
• 打造獨特個性：撰寫定義角色特徵的核心指令。
• 賦予超能力：提供工具，讓模型存取網際網路上的即時資訊。
• 設計專屬外觀：使用 AI 生成獨一無二的虛擬化身。

完成課程後，您將能建立功能齊全的專屬 AI 夥伴。

架構

我們的應用程式採用簡單但功能強大的模式。我們有一個提供 API 的 Python 後端。這個後端會包含 ADK 代理，也就是「大腦」。任何使用者介面 (例如骨架應用程式中的 JavaScript 前端、行動應用程式，甚至是指令列工具) 都能透過 API 與這個大腦互動。

此外，我們還會運用 Antigravity CLI 內建的圖像生成功能，指示其為 AI 伴侶生成獨特外觀。

取得 Gemini API 金鑰

繼續操作前，您需要 Gemini API 金鑰，才能透過 Google AI Studio 驗證要求。

1. 前往 Google AI Studio。
2. 使用 Google 帳戶登入。
3. 按一下左上選單中的「取得 API 金鑰」按鈕。
4. 按一下「建立 API 金鑰」 (您可以在新的或現有的 Google Cloud 專案中建立)。
5. 複製產生的金鑰。請妥善保管這個私密金鑰。

建立及設定專案

如要存取 Cloud Shell，您仍須具備 Google Cloud 專案。如果沒有：

1. 前往 Google Cloud 控制台。
2. 在控制台的頂端導覽列中，按一下「Select a project」(選取專案)，然後按一下右上角的「New Project」(新專案)。
3. 為專案命名，然後按一下「建立」。(無須加入機構)。
4. 建立專案後，請從控制台頂端的專案下拉式選單中選取專案。

專案現已設定為允許存取 Cloud Shell。

2. 事前準備

👉按一下 Google Cloud 控制台頂端的「啟用 Cloud Shell」(這是 Cloud Shell 窗格頂端的終端機形狀圖示)，

👉💻 在 Cloud Shell 終端機中安裝 Antigravity CLI：

curl -fsSL https://antigravity.google/cli/install.sh | bash

👉💻 如要在全域使用「agy」CLI，請將其新增至 Shell 設定檔：

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

1. 選擇選項 1。按下 Enter 即可使用 Google OAuth。
2. 按照提示開啟瀏覽器，使用 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.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

CLI 會執行指令，並確認伺服器正在運作中。您會留在互動式 CLI 工作階段。

👀 如要查看應用程式，請按一下 Cloud Shell 工具列中的「網頁預覽」圖示。選取「變更通訊埠」，將通訊埠設為 5000，然後按一下「變更並預覽」。系統會顯示網站預覽畫面。

初始應用程式只是傀儡。目前還沒有智慧功能。無論傳送什麼訊息，系統都會重複回覆。這可確認基本網頁伺服器運作正常，我們才能加入 AI。別忘了開啟音箱！

3. 使用 Antigravity CLI 建立角色

現在，我們來建立智慧型同伴的核心。由於 Antigravity CLI 已在終端機中執行，並管理背景網路伺服器，您可以直接在互動式工作階段中繼續操作。

我們將使用 CLI 建構 Agent。代理不只是對語言模型的簡單呼叫，而是 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".

按下 Enter 鍵，核准 agy 寫入檔案的要求。

CLI 會生成 Python 程式碼。

👉按一下「Open Editor」按鈕 (類似於有鉛筆的開啟資料夾)。視窗中會開啟 Cloud Shell 程式碼編輯器。左側會顯示檔案總管。

👉 使用編輯器，前往 companion-python 資料夾下的 character.py。請花點時間檢查 model= 行，如果選擇其他模型，請手動編輯為 gemini-3.5-flash。這樣才能確保研討會的後續內容一致。

注意：大型語言模型可能具有不確定性，這是 AI 輔助開發中的重要概念。「不確定性」是指即使提示完全相同，模型每次產生的結果也可能略有不同。這項功能會運用創意生成程式碼，因此註解、間距，甚至是暫時變數的命名方式都可能有所不同。不過，核心邏輯和結構應與要求的功能相同。

因此，使用 AI 輔助程式設計時，很少會只下達一次指令。在實際專案中，開發人員會將其視為對話。首先，您要提出廣泛的要求 (就像我們剛才所做)，然後查看輸出內容，再使用後續提示進行修正，例如：

• 「太棒了，現在請新增註解，說明每一行。」
• 「Can you refactor that into a separate function?」(可以將該函式重構為獨立函式嗎？)
• 「請為 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.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

👀 前往網頁預覽分頁。

👉 類型：

Hello, how are you?

然後按下「傳送」。現在代理應會回覆親切的問候語，而不是只重複你的話！這表示代理程式現在已採用 Gemini 技術。

4. 強化代理的 Persona

簡單的指令很實用，但詳細的角色設定能創造更引人入勝、令人難忘的角色。在這個步驟中，您將設計專屬的同伴個性，然後指示 Antigravity CLI 直接修改代理程式的程式碼，採用這個新角色。

發想同伴的形象

首先，請花點時間想想要建立的 AI 夥伴。現在正是發揮創意的好時機！以下是一些可供參考的問題：

• 名稱是什麼？(例如 Sparky、Codex、Captain AI、Professor Know-it-all)
• 核心特質為何？(例如：友善好奇、機智諷刺、正式專業、開朗的海盜？)
• 該機構的角色或專業領域為何？(例如：一般用途的助理、程式設計專家、創意寫作夥伴、健身教練？)
• 有哪些規則是 AI 助理一律要遵守的？(例如「一律先打招呼」、「絕不透露自己是 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 在每次與使用者互動前都會參考的基礎背景資訊。這項參數會決定代理的個性、語氣、必須遵守的規則，以及應對方式。精心設計的指令是區分一般聊天機器人和可信、一致的角色之關鍵。因此，我們即將製作的提示非常重要，因為這會直接將這個個性注入代理程式的大腦。

👉✨ 返回 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]

按下 Enter 鍵，核准 agy 寫入檔案的要求。

測試新角色

Antigravity CLI 會為 character.py 產生更新後的程式碼。為確保伺服器採用新的代理程式設定，請使用 Antigravity CLI 重新啟動伺服器。

👉✨ 在 Antigravity CLI 提示中，貼上下列要求：

Please restart the Python web server for me.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

👀 在網頁預覽畫面中，與你的 AI 幫手對話。向 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.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

CLI 會修改 character.py 檔案，使用用戶端層級的重試政策自動處理速率限制。請記得在 CLI 更新檔案後，要求重新啟動網路伺服器：

Please restart the Python web server for me.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

5. 新增近期事件的基礎

現在，我們的代理人充滿個性，但有一項重大限制：知識會根據訓練資料凍結在特定時間點。無法提供昨天的新聞或最近的發現。為解決這個問題，我們為代理提供工具。

工具就像是您賦予代理程式的超能力或特殊能力。代理程式本身只能說話，有了搜尋工具，就能瀏覽網際網路。日曆工具可以查看你的行程。從技術上來說，工具是特定的函式或 API，當代理程式發現自身知識不足以回答使用者的要求時，可以智慧地選擇使用。

在進階系統中，工具可由外部系統提供，例如 MCP (Model Context Protocol) 伺服器。但這個步驟不需要獨立伺服器。ADK 隨附強大的預先建構google_search工具，可輕鬆新增至代理的功能。

現在就讓 Google 搜尋成為你的得力助手。

👉 在 Cloud Shell 編輯器中，開啟 companion-python 下的 character.py，並修改如下：

• 從 google.adk.tools 匯入 google_search。
• 將 tools 清單新增至 LlmAgent 建構函式。
• 更新 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
)

測試 Grounded Agent

如要確保網路伺服器使用 google_search 工具載入新程式碼，請要求 Antigravity CLI 重新啟動。

👉✨ 在 Antigravity CLI 提示中，貼上下列要求：

Please restart the Python web server for me.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

👉 在網頁預覽中，提出需要最新知識的問題，例如：

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.

按下 Enter 鍵，核准 agy 寫入檔案的要求。

這項工具會產生張嘴和閉嘴的圖片，並自動儲存在專案的 static/images 目錄中。

現在可以與視覺化自訂的同伴互動了！

恭喜！

您已成功建構出精巧的 AI 夥伴！您從基本應用程式開始，使用 Antigravity CLI 搭建代理程式架構，賦予豐富的個性，並提供工具，讓代理程式存取即時資訊，甚至生成自己的虛擬化身。您現在可以建構更複雜且功能強大的 AI 代理。

👉💻 如要結束並關閉工作階段，請返回終端機，在 agy 提示中輸入 /exit，退出 Antigravity CLI：

/exit