1. 学习内容
- 如何安装和注册 Antigravity CLI 的技能，以在特定框架 (ADK) 中启用编码功能。
- 如何使用 Antigravity CLI 生成完整的 ADK 代理配置。
- 如何通过改进指令来增强智能体的个性。
- 如何通过为代理提供
google_search来让其回答有关近期活动的问题，从而为代理添加“依据”。
AI 伴侣应用
在此 Codelab 中，您将打造一个生动有趣的互动式 AI 伴侣。这不仅仅是一个标准的文本输入/输出聊天机器人。想象一下，有一个角色生活在网页上。您输入消息后，角色不仅会以文字形式回复，还会看着您大声回复，并且嘴巴会随着说出的文字同步移动。
您将从一个预构建的 Web 应用（一个有面孔但没有自己想法的数字“傀儡”）开始。它只能重复您输入的内容。您的任务是从头开始构建其大脑和个性。
在本研讨会中，您将逐步添加智能和自定义层，将这个简单的傀儡变成一个独特而强大的伙伴。您将：
- 使用 ADK(Python) 赋予其核心智能，使其能够理解和生成语言。
- 通过编写定义其性格的核心指令，打造其独特的个性。
- 通过为 Gemini 提供可访问互联网实时信息的工具，赋予其超能力。
- 设计自定义外观：使用 AI 生成独特的虚拟形象。
完成本课程后，您将拥有一个由您创建的、功能完备且个性化的 AI 伴侣。
架构
我们的应用遵循一种简单但强大的模式。我们有一个提供 API 的 Python 后端。此后端将包含我们的 ADK 智能体，该智能体充当“大脑”。任何用户界面（例如框架应用中的 JavaScript 前端、移动应用，甚至是命令行工具）随后都可以通过 API 与此大脑进行互动。
除此之外，我们还将利用 Antigravity CLI 内置的图片生成功能，指示它为我们的 AI 伴侣生成独特的外观。
获取 Gemini API 密钥
在继续操作之前，您需要一个 Gemini API 密钥，以便通过 Google AI Studio 对您的请求进行身份验证。
- 前往 Google AI Studio。
- 使用您的 Google 账号登录。
- 点击左上角菜单中的 Get API key（获取 API 密钥）按钮。
- 点击创建 API 密钥（您可以在新的或现有的 Google Cloud 项目中创建 API 密钥）。
- 复制生成的密钥。请确保此密钥的私密性和安全性。
创建和配置项目
如需访问 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，请将其添加到 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 智能体开发套件 (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。Google OAuth，请按
Enter。 - 按照提示打开浏览器，使用您的 Google 账号进行身份验证，然后按照说明登录。
现在，您已进入 Antigravity CLI 互动提示界面！
通过 Antigravity CLI 启动 Web 服务器
由于 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，然后点击“更改并预览”。系统会显示您网站的预览。
初始应用只是一个傀儡。它目前还没有智能功能。无论您发送什么消息，它都会简单地重复您发送的消息。这可确认我们的基本 Web 服务器在添加 AI 之前可正常运行。请记得打开扬声器！
3. 使用 Antigravity CLI 创建角色
现在，我们来创建伴侣智能的核心。由于 Antigravity CLI 已在终端中运行并管理后台 Web 服务器，因此您可以直接在互动式会话中继续操作。
我们将使用 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 进行编码很少是一次性命令。在实际项目中，开发者会将其视为对话。首先，您提出一个宽泛的要求（就像我们刚才所做的那样），然后查看输出内容，再通过后续提示进行优化，例如：
- “太棒了，现在添加注释来解释每一行。”
- “您能否将其重构为单独的函数？”
- “请为 API 调用添加错误处理。”
通过这种迭代式对话过程，您可以与 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 重新启动 Web 服务器。
👉✨ 在 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 在每次与用户互动之前都会参考的基础背景信息。它决定了智能体的个性、语气、必须遵守的规则以及应如何展示自己。精心设计的指令是通用聊天机器人与可信且前后一致的角色之间的区别。因此，我们即将编写的提示至关重要，因为它会直接将这种个性注入到代理的“大脑”中。
👉✨ 返回 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 更新文件后，让其重启 Web 服务器：
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
)
测试 Grounded Agent
如需确保 Web 服务器使用 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