Мастер-класс для начинающих по Antigravity CLI и ADK (Создайте своего первого ИИ-компаньона)

1. Чему вы научитесь

• Как установить и зарегистрировать навык для Antigravity CLI, чтобы включить возможности программирования в рамках определенного фреймворка (ADK).
• Как использовать интерфейс командной строки Antigravity для генерации полной конфигурации агента ADK.
• Как улучшить личностные качества агента, скорректировав его инструкции.
• Как добавить функцию "привязки" к вашему агенту, указав ему google_search для ответа на вопросы о недавних событиях.

Приложение-компаньон с искусственным интеллектом

В этом практическом занятии вы воплотите в жизнь визуального интерактивного ИИ-компаньона. Это больше, чем просто стандартный чат-бот, вводящий и выводящий текст. Представьте себе персонажа, живущего на веб-странице. Вы набираете сообщение, и вместо простого текста в ответ, персонаж смотрит на вас и отвечает вслух, при этом его рот двигается синхронно со словами.

Вы начнёте с готового веб-приложения — цифровой «марионетки», у которой есть лицо, но нет собственного разума. Она может только повторять то, что вы печатаете. Ваша задача — создать её мозг и личность с нуля.

В ходе этого мастер-класса вы постепенно будете добавлять уровни интеллекта и персонализации, превращая эту простую куклу в уникального и способного компаньона. Вы сможете:

• Наделение его базовым интеллектом с использованием ADK (Python) для понимания и генерации языка.
• Формирование его уникальной индивидуальности путем написания основных инструкций, определяющих его характер.
• Наделить его сверхспособностями , предоставив ему инструменты для доступа к информации в режиме реального времени из интернета.
• Создание уникального внешнего вида с помощью искусственного интеллекта для генерации неповторимого аватара.

В итоге вы получите полностью функционального и персонализированного ИИ-компаньона, созданного вами.

Архитектура

Наше приложение построено по простой, но мощной схеме. У нас есть бэкенд на Python, который обслуживает API. Этот бэкенд будет содержать наш агент ADK, который выступает в роли «мозга». Любой пользовательский интерфейс (например, фронтенд на JavaScript из базового приложения, мобильное приложение или даже инструмент командной строки) может взаимодействовать с этим «мозгом» через API.

Кроме того, мы воспользуемся возможностями генерации изображений, встроенными в интерфейс командной строки Antigravity, и дадим ему указание создать уникальный внешний вид для нашего ИИ-компаньона.

Получите ключ API Gemini.

Прежде чем продолжить, вам потребуется ключ API Gemini для аутентификации запросов в Google AI Studio.

1. Перейдите в Google AI Studio .
2. Войдите в систему, используя свою учетную запись Google.
3. Нажмите кнопку «Получить ключ API» в меню в верхнем левом углу.
4. Нажмите «Создать ключ API» (его можно создать в новом или существующем проекте Google Cloud).
5. Скопируйте сгенерированный ключ. Храните этот ключ в тайне и безопасности.

Создание и настройка проекта

Для доступа к Cloud Shell вам по-прежнему потребуется проект Google Cloud. Если у вас его нет:

1. Перейдите в консоль Google Cloud .
2. В верхней панели навигации консоли нажмите «Выбрать проект» , а затем в правом верхнем углу нажмите «Новый проект» .
3. Присвойте проекту имя и нажмите «Создать» . (Название организации не требуется).
4. После создания проекта выберите его из выпадающего списка проектов в верхней части консоли.

Ваш проект теперь настроен для доступа через Cloud Shell.

2. Прежде чем начать

👉Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud (это значок терминала в верхней части панели Cloud Shell).

👉💻 Установите Antigravity CLI в терминале Cloud Shell:

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

👉💻 Чтобы использовать интерфейс командной строки 'agy' глобально, добавьте его в свой профиль оболочки:

echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

👉💻 Экспортируйте свой API-ключ Gemini и сохраните его локально в терминале 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:

• Откройте консоль Google Cloud: https://console.cloud.google.com
• Выберите проект, который вы хотите использовать для этого мастер-класса, из выпадающего списка проектов в верхней части страницы.
• Идентификатор вашего проекта отображается в карточке с информацией о проекте на панели управления.

👉💻 В терминале клонируйте проект bootstrap с GitHub:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

👉💻 Запустите скрипт инициализации. Этот скрипт предложит вам ввести идентификатор вашего проекта Google Cloud . Затем введите идентификатор проекта Google Cloud, найденный на предыдущем шаге, когда скрипт init.sh запросит это.

cd ~/companion-python
./init.sh

👉💻 Укажите необходимый идентификатор проекта:

gcloud config set project $(cat ~/project_id.txt) --quiet

👉💻 Выполните следующую команду, чтобы включить необходимые API Google Cloud (для предварительного просмотра/хостинга Cloud Shell требуется только Compute Engine):

gcloud services enable compute.googleapis.com

Установите навыки разработчика ADK.

Чтобы позволить Antigravity CLI ( agy ) понимать и писать код с использованием Python Agent Development Kit (ADK), нам необходимо установить созданный нами навык разработчика Python для ADK в рабочую область проекта.

👉💻 Создайте локальную директорию навыков агента и скопируйте файл навыка:

mkdir -p ~/companion-python/.agents/skills/adk-python
cp ~/companion-python/skills/skill.md ~/companion-python/.agents/skills/adk-python/SKILL.md

Это регистрирует навык локально в рамках проекта. При запуске agy он автоматически обнаружит и загрузит этот навык, что позволит ему писать, редактировать и управлять агентами ADK.

👉💻 Запустите интерфейс командной строки Antigravity в терминале Cloud Shell:

cd ~/companion-python
agy

[!ВАЖНО] Вход в интерфейс командной строки Antigravity

При первом запуске команды 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. Используйте Google OAuth , нажав Enter .
2. Следуйте инструкциям, чтобы открыть браузер, авторизуйтесь с помощью своей учетной записи Google и войдите в систему.

Теперь вы находитесь в интерактивной командной строке Antigravity!

Запустите веб-сервер через интерфейс командной строки Antigravity.

Поскольку интерфейс командной строки Antigravity может выполнять команды, давайте попросим его запустить сервер в фоновом режиме вашей сессии.

👉✨ В командной строке Antigravity вставьте следующий запрос:

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 на запись файла.

Интерфейс командной строки выполнит команду и подтвердит запуск сервера. Вы останетесь в интерактивном сеансе командной строки.

👀 Чтобы открыть приложение, нажмите значок предварительного просмотра веб-страниц на панели инструментов Cloud Shell. Выберите «Изменить порт», установите значение 5000 и нажмите «Изменить и просмотреть». Отобразится предварительный просмотр вашего веб-сайта.

Первоначальное приложение — всего лишь марионетка. У него пока нет интеллекта. Какое бы сообщение вы ни отправили, оно просто повторит его. Это подтверждает работоспособность нашего базового веб-сервера перед добавлением ИИ. Не забудьте включить динамик!

3. Создайте персонажа с помощью интерфейса командной строки Antigravity.

Теперь давайте создадим ядро ​​интеллекта нашего компаньона. Поскольку интерфейс командной строки Antigravity уже запущен в вашем терминале и управляет фоновым веб-сервером, вы можете продолжить работу непосредственно в интерактивной сессии.

Мы используем интерфейс командной строки для создания агента . Агент — это больше, чем просто вызов языковой модели; это «мозг» или центральный контроллер нашего ИИ. Представьте его как отдельную сущность, способную рассуждать, следовать определенному набору инструкций (его личность) и в конечном итоге использовать инструменты для выполнения задач. В нашем проекте этот агент — компонент, который будет получать сообщения от пользователей, воплощать уникальную личность нашего компаньона и формулировать интеллектуальные, соответствующие характеру персонажа ответы.

👉✨ В командной строке 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 на запись файла.

Интерфейс командной строки сгенерирует код на Python.

👉Нажмите на кнопку «Открыть редактор» (она выглядит как открытая папка с карандашом). Это откроет редактор кода Cloud Shell в окне. Слева вы увидите файловый менеджер.

👉 Воспользуйтесь редактором и перейдите к character.py в папке companion-python . Пожалуйста, уделите немного времени проверке строки model= и вручную измените её на gemini-3.5-flash если была выбрана другая модель. Это обеспечит единообразие на протяжении всего нашего мастер-класса.

Примечание: Большие языковые модели могут быть недетерминированными, и это ключевое понятие в разработке с использованием ИИ. «Недетерминированность» означает, что даже при одном и том же запросе модель может каждый раз выдавать немного разные результаты. Она использует свой творческий подход для генерации кода, поэтому вы можете увидеть различия в комментариях, пробелах или даже в именовании временных переменных. Однако основная логика и структура должны быть функционально идентичны тому, что было запрошено.

Вот почему программирование с использованием ИИ редко бывает разовой командой. В реальном проекте разработчики относятся к этому как к диалогу. Вы начинаете с общего запроса (как мы только что сделали), анализируете результат, а затем уточняете его с помощью дополнительных подсказок, таких как:

• «Отлично, теперь добавьте комментарии с пояснениями к каждой строке».
• "Не могли бы вы выделить это в отдельную функцию?"
• «Пожалуйста, добавьте обработку ошибок для вызова API».

Этот итеративный, диалоговый процесс позволяет вам сотрудничать с ИИ, направляя его до тех пор, пока код не станет именно таким, каким вы его хотите видеть. На этом семинаре мы будем использовать конкретные, прямые подсказки, но помните, что в ваших собственных проектах именно диалог является источником настоящей силы! Главное, чтобы структура кода, сгенерированная 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 , давайте попросим CLI Antigravity перезапустить веб-сервер.

👉✨ В командной строке Antigravity вставьте следующий запрос:

Please restart the Python web server for me.

Нажмите Enter, чтобы подтвердить запрос agy на запись файла.

👀 Перейдите во вкладку предварительного просмотра веб-страниц.

👉 Тип:

Hello, how are you?

и нажмите «Отправить». Теперь агент должен ответить дружелюбным приветствием, а не просто повторить ваши слова! Это подтверждает, что наш агент теперь работает на платформе Gemini.

4. Улучшить образ агента.

Простая инструкция — это хорошо, но детально проработанный образ создает гораздо более привлекательного и запоминающегося персонажа. На этом этапе вы разработаете личность своего компаньона, а затем дадите указание интерфейсу командной строки Antigravity напрямую изменить код агента, чтобы он принял этот новый образ.

Продумайте характер вашего компаньона.

Для начала, уделите немного времени тому, чтобы обдумать, какого ИИ-компаньона вы хотите создать. Это ваш шанс проявить творчество! Вот несколько вопросов, которые помогут вам начать:

• Как его зовут? (например, Спарки, Кодекс, Капитан ИИ, Профессор Всезнайка)
• В чём заключается его главная черта характера? (например, дружелюбный и любознательный, остроумный и саркастичный, формальный и профессиональный, весёлый пират?)
• Какова его роль или специализация? (например, универсальный помощник, эксперт по программированию, партнер по творческому письму, фитнес-тренер?)
• Какие правила ему следует всегда соблюдать? (например, «Всегда начинайте с приветствия», «Никогда не раскрывайте, что вы — ИИ», «Используйте смайлики в своих ответах»).

Пример персонажа:

 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.

Теперь, когда вы разработали личность своего компаньона на бумаге, пришло время воплотить её в жизнь в коде. Самая важная часть агента ADK — это его параметр instruction . Представьте это как основную программную часть агента, его «главную директиву» или конституцию, которой он всегда должен следовать.

Эта инструкция — ключ к управлению поведением агента. Это не просто предложение; это основополагающий контекст, к которому ИИ обращается перед каждым взаимодействием с пользователем. Она определяет личность агента, тон его голоса, правила, которым он должен подчиняться, и то, как он должен себя представлять. Хорошо составленная инструкция — это разница между обычным чат-ботом и убедительным, последовательным персонажем. Поэтому подсказка, которую мы собираемся создать, имеет решающее значение, поскольку она напрямую внедрит эту личность в мозг нашего агента.

👉✨ Вернитесь в интерфейс командной строки Antigravity и используйте этот шаблон. Замените текст в скобках описанием вашей персоны. ЗАМЕНИТЕ [ВАШЕ ОПИСАНИЕ ПЕРСОНЫ ЗДЕСЬ] на предпочитаемую вами персону.

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 сгенерирует обновлённый код для character.py . Чтобы убедиться, что сервер подхватит новую конфигурацию агента, давайте попросим интерфейс командной строки Antigravity перезапустить его.

👉✨ В командной строке Antigravity вставьте следующий запрос:

Please restart the Python web server for me.

Нажмите Enter, чтобы подтвердить запрос agy на запись файла.

👀 В режиме предварительного просмотра веб-страницы пообщайтесь со своим персонажем. Спросите: how are you? ». Его ответ теперь должен идеально соответствовать уникальному персонажу, которого вы создали!

Добавить обработку повторных попыток для ограничений скорости запросов API (необязательно, но рекомендуется).

Во время семинаров или в периоды высокой интенсивности использования вы можете столкнуться с ошибками превышения лимита запросов к API (HTTP 429: Resource Exhausted). Чтобы обеспечить бесперебойную работу вашего приложения и автоматическую обработку исключений, связанных с превышением лимита запросов, мы можем настроить параметры повторных попыток, встроенные непосредственно в параметры клиента Google GenAI SDK.

👉✨ В командной строке Antigravity вставьте следующий запрос:

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 на запись файла.

Интерфейс командной строки автоматически изменит ваш файл character.py для обработки ограничений скорости запросов с помощью политик повторных попыток на уровне клиента. Не забудьте попросить интерфейс командной строки перезапустить веб-сервер после обновления файла:

Please restart the Python web server for me.

Нажмите Enter, чтобы подтвердить запрос agy на запись файла.

5. Добавьте привязку к недавним событиям.

Наш агент теперь обладает ярко выраженной индивидуальностью, но у него есть существенное ограничение: его знания застыли во времени, основаны на данных, на которых он обучался. Он не может рассказать вам о вчерашних новостях или недавних открытиях. Чтобы преодолеть это, мы предоставляем агентам инструменты .

Представьте себе инструменты как сверхспособности или особые возможности, которые вы наделяете своего агента. Сам по себе агент может только говорить. С помощью инструмента поиска он получает возможность просматривать интернет. С помощью календаря он может проверить ваше расписание. Технически, инструмент — это определенная функция или API, которые агент может разумно использовать, когда понимает, что его собственных знаний недостаточно для ответа на запрос пользователя.

В продвинутых системах инструменты могут предоставляться внешними системами, такими как серверы MCP (Model Context Protocol) . Но для этого шага нам не нужен отдельный сервер. ADK поставляется с мощным, предварительно настроенным инструментом google_search , который мы можем легко добавить в функциональные возможности нашего агента.

Давайте наделим нашего компаньона возможностями поиска Google.

👉 В редакторе Cloud Shell откройте character.py в папке companion-python и внесите в него следующие изменения:

• Импортируйте google_search из google.adk.tools .
• Добавьте список 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
)

Проверьте агента, находящегося на земле.

Чтобы убедиться, что веб-сервер загрузит ваш новый код с инструментом google_search , попросите CLI Antigravity перезапустить его.

👉✨ В командной строке Antigravity вставьте следующий запрос:

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 вашего проекта.

Теперь вы можете взаимодействовать со своим визуально настроенным компаньоном!

Поздравляем!

Вы успешно создали сложного ИИ-компаньона! Вы начали с базового приложения, использовали интерфейс командной строки Antigravity для создания агента, наделили его богатой индивидуальностью и оснастили инструментами для доступа к информации в реальном времени и даже генерации собственного аватара. Теперь вы готовы создавать еще более сложные и функциональные ИИ-агенты.

👉💻 Чтобы завершить сессию, вернитесь в терминал и выйдите из Antigravity CLI, набрав /exit в командной строке agy :

/exit