Создание простого агента для путешествий с помощью ADK и Gemini CLI

1. Введение

Последнее обновление: 22 июня 2026 г.

Создание простого турагентства с помощью ADK

Добро пожаловать на семинар по ADK Python(*), который включает в себя все необходимое благодаря Gemini CLI!

Эта практическая работа состоит из двух 🏅 этапов:

1. Простой и распространенный учебный план: настройка + мгновенное вознаграждение.
2. Персонализированный путь, на котором вы выбираете квест, который нужно решить с помощью Gemini CLI

Вторая часть практической работы идеально подходит для хакатона (с призами за самые креативные решения).

Этап 1. Создание первого агента с помощью ADK и Gemini CLI

Цель этого этапа – пошагово создать простого агента для путешествий с помощью ADK. Для этого сначала нужно настроить Gemini CLI, чтобы он помогал нам писать код с помощью ADK. Это позволит вашей локальной оболочке выбирать последнюю версию Python ADK, анализировать код и документацию и предоставлять самый свежий и лучший код для работы с ним в соответствии с вашей целью.

Это пошаговое руководство, в котором мы создадим полностью работающее приложение, постепенно добавляя в него новые функции. Обычно это занимает около одного часа (плюс время на установку).

Примечание (*). Хотя в практической работе предполагается, что вы используете Python ADK, вы можете использовать Go, Java или TypeScript с минимальными изменениями. Если вы использовали ADK только с Python, эта практическая работа – отличный шанс попробовать другой язык. Поделитесь своим мнением, перейдя по ссылке ниже.

Этап 2. Расширение возможностей агента

После этого мы предлагаем вам дюжину вариантов (разной сложности) для расширения приложения по вашему вкусу. Это позволит вам изучить разные аспекты (интерфейс, операции, сложные взаимодействия агента и т. д.).

Что вы создадите

В этой практической работе вы создадите приложение турагентства с помощью ADK и Gemini CLI. Приложение будет:

• Подключитесь к API Airbnb через MCP Airbnb.
• Искать в интернете актуальную информацию (погода, даты и т. д.)
• Выполнять действия с помощью собственных инструментов.
• Создайте изображения квартир и комнат с помощью Nano Banana.

Gemini CLI поможет вам во всем этом: напишет или проверит код и найдет последние документы в локальном зеркале репозитория ADK (на Python или вашем любимом языке).

Что вы узнаете

• Как создать приложение с помощью ADK
• Как использовать Gemini CLI для написания кода приложений на основе локальных документов
• Как взаимодействовать с MCP-сервером, чтобы подключаться к внешним источникам данных в реальном времени, например:

Что вам понадобится

• Компьютер, на который можно устанавливать пакеты (например, npm install ..).
• Базовые навыки программирования на Python, TypeScript, Go или Java.
• Настоятельно рекомендуется использовать IDE (Antigravity, VS Code, IntelliJ, Vim).

Почему ADK + Gemini CLI?

Возможно, вы задаетесь вопросом: зачем использовать ADK (SDK для создания агентов) вместе с локальным помощником по написанию кода (например, Gemini CLI)? Оба инструмента очень мощные, но их взаимодействие нетривиально. Многие пытались использовать их вместе, но безуспешно (в основном из-за проблем с циклом в цикле). В этой практической работе мы расскажем, как это сделать.

2. Подготовка

Выберите один из следующих вариантов: Самостоятельная настройка среды, если вы хотите выполнить эту практическую работу на своем компьютере, или Запустить Cloud Shell, если вы хотите выполнить эту практическую работу полностью в облаке.

Самостоятельная настройка среды

1. Войдите в консоль Google Cloud и создайте новый проект или выберите существующий. Если у вас нет аккаунта Gmail или Google Workspace, создайте его.

• Название проекта – это отображаемое название для участников проекта. Это строка символов, которая не используется API Google. Вы можете изменить его в любое время.
• Идентификатор проекта уникален для всех облачных проектов Google Cloud и не может быть изменен после создания. Консоль Cloud автоматически генерирует уникальную строку. Обычно ее значение не имеет значения. В большинстве практических работ вам нужно будет ссылаться на идентификатор проекта (обычно обозначаемый как PROJECT_ID). Если вам не нравится сгенерированный идентификатор, вы можете сгенерировать другой случайный. Вы также можете попробовать ввести свой вариант и проверить, доступен ли он. После этого шага его нельзя будет изменить, и оно останется на протяжении всего проекта.
• Для некоторых API используется третье значение – номер проекта. Подробную информацию обо всех трех значениях можно найти в документации.

Внимание! Идентификатор проекта должен быть уникальным. После того как вы его выберете, никто другой не сможет его использовать. Вы единственный пользователь этого идентификатора. Даже если проект удален, его идентификатор нельзя использовать повторно.

Примечание. Если вы используете аккаунт Gmail, можно оставить местоположение по умолчанию – Нет организации. Если вы используете аккаунт Google Workspace, выберите местоположение, которое подходит для вашей организации.

2. Затем вам нужно будет включить платежный аккаунт в Cloud Console, чтобы использовать ресурсы и API Cloud. Выполнение этой практической работы не потребует больших затрат, если они вообще будут. Чтобы избежать дополнительных расходов, вы можете удалить созданные ресурсы или проект. Новые пользователи Google Cloud могут получить 300 долларов США на бесплатный пробный период.

Запустите Cloud Shell

Хотя Google Cloud можно управлять удаленно с ноутбука, в этой практической работе вы будете использовать Google Cloud Shell – среду командной строки, работающую в облаке.

В консоли Google Cloud нажмите на значок Cloud Shell на панели инструментов в правом верхнем углу.

Инициализация и подключение к среде займут всего несколько минут. После завершения вы увидите примерно следующее:

На этой виртуальной машине установлены все необходимые инструменты разработки. Она предлагает постоянный домашний каталог объемом 5 ГБ и работает на платформе Google Cloud, что значительно повышает производительность сети и аутентификацию. Все действия в рамках этой практической работы можно выполнить в браузере. Ничего устанавливать не нужно.

3. Требования (установка)

Примечание. Если вы решите выполнить эту практическую работу в Cloud Shell, то Python, uv и Gemini CLI (gemini) уже будут предустановлены.

Для работы с этим руководством вам нужно установить:

1. Python и uv

python и uv (менеджер пакетов для Python). Это необходимо для ADK. Убедитесь, что у вас установлен uv:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Почему uv? Вы можете использовать любой менеджер Python, но с uv настройки ENV/PATH для Python будут одинаковыми для вас и Gemini CLI, поэтому работа с оболочкой будет практически такой же, как и с Gemini CLI. Например, если вы используете virtualenv, Gemini CLI будет вынужден выполнять такие действия, как "source .env/venv/bin/activate && my-original-command", чтобы имитировать вашу среду.

2. Gemini CLI

Инструкции по установке Gemini CLI можно найти на странице https://github.com/google-gemini/gemini-cli.

# Note: This requires having npm or npx installed.
npm install -g @google/gemini-cli

1. На Mac можно использовать brew, как указано в официальной документации.
2. В Windows можно использовать chocolatey или просто скачать исполняемый файл с сайта https://nodejs.org/en/download.

Для шага 4 вам также понадобится приложение npx. npm и npx должны быть доступны в Gemini CLI. Если нет, попросите Gemini CLI помочь вам.

Аутентификация

Вам понадобится проект Google Cloud с включенным Vertex AI или ключ Google AI Studio API.

Вариант А (рекомендуется для семинара). Экспортируйте ключ API:

export GOOGLE_API_KEY="your-api-key"

Вариант Б (Vertex AI). Выполните аутентификацию с помощью gcloud:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud auth application-default login

Как настроить рабочую среду

Вы создадите СОБСТВЕННОЕ решение в каталоге mysolution/. Давайте создадим папку и два нужных файла.

Теперь вы можете открыть папку в IDE (Visual Studio Code, IntelliJ, RubyMine и т. д.).

# 1. Find an empty directory, and download this repo.
git clone https://github.com/palladius/adk-gemini-cli-workshop
cd adk-gemini-cli-workshop/

# 2. Create your solution empty skeleton
mkdir -p mysolution/
touch mysolution/__init__.py mysolution/agent.py

# 3. This installs ADK and MCP via `uv` by reading pyproject.toml
uv init
uv sync

# 4. Call Gemini CLI
gemini  # This runs Gemini CLI under the adk-gemini-cli-workshop/ folder.
# Login with your GMail account.

Команда uv sync не является обязательной, но если она не выполняется, значит вам нужно исправить установку Python или uv. В папке ./.venv/bin/ должны появиться adk и другие полезные скрипты.

Чтобы проверить настройки, запустите make test-step1 и убедитесь, что не получаете 403 PERMISSION DENIED..

Важно! Убедитесь, что вы запускаете Gemini CLI из папки 📁 adk-gemini-cli-workshop/. Кроме того, в IDE это название должно быть указано как корневое. Это позволит Gemini CLI использовать правильную конфигурацию. Вы всегда можете добавить внешние папки через /dir add /your/other/folder, но 📁 adk-gemini-cli-workshop/ – лучшее место для начала.

Доступные решения

Весь код находится в папке 📂 steps/. Вы можете скопировать код оттуда.

Эта практическая работа не о том, как писать хороший код ADK, а о том, как настроить среду, чтобы ХОРОШИЙ код автоматически писался под вашим руководством.

1. Как установить программное обеспечение
2. настройка и запуск;
3. вступая в праведный цикл обратной связи

Вот что мы действительно хотим, чтобы вы здесь узнали. Вы также можете протестировать их все одновременно с помощью $ make web-4steps!

4. Шаг 1. Базовый агент

Давайте начнем с создания базового агента, который может вести разговор.

Добавьте в файл mysolution/__init__.py следующий контент:

from .agent import root_agent

Вот и все! Это позволит ADK узнать, где находится ваш код (в agent.py).

Добавьте в файл mysolution/agent.py следующий контент:

from google.adk.agents import Agent

root_agent = Agent(
    name="travel_basic",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant." +
    "You can help with general travel advice based on your knowledge.",
)

Тестирование агента

Это касается всех шагов. ADK позволяет тестировать агента двумя способами: через CLI и веб-интерфейс.

• CLI лучше всего подходит для быстрых и автоматизированных тестов.
• Веб-версия лучше всего подходит для визуального контроля, использования микрофона (!) и устранения неполадок.

Совет. Для выполнения этого упражнения (за исключением модульного тестирования) используйте веб-версию. Это просто потрясающе! Используйте CLI только для автоматизированного тестирования.

Хороший запрос, который правильно проверяет шаги 1-2-3-4, может быть таким (умный "лакмусовый запрос"):

Здравствуйте! Я хочу забронировать номер в отеле в центре Парижа на завтрашний вечер на одного человека на одну ночь. Удобное расположение рядом с Лионским вокзалом. Бюджет: до 200 евро за ночь.

1. Скажи, какой завтра день недели и дата в формате ГГГГММДД.
2. Скажи, какие отели доступны на завтра (хотя бы три). Я хочу видеть: > цену, адрес, рейтинг (в формате XX/YY, например "4,7/5" – из поиска отелей в Google, Booking или Airbnb), количество отзывов. Представь их в виде таблицы. Желательно, чтобы название гостиницы было связано с ее URL (не нужно добавлять столбец URL). Убедитесь, что ссылка работает и ведет на страницу с информацией об отеле.

Это умный запрос, поскольку он проверяет время и отели и будет по-разному завершаться ошибкой на шагах 1, 2, 3 и должен полностью завершиться успешно только на шаге 4. Конечно, вы можете использовать любой запрос.

Запустите его из bash (CLI):

# 1. If ADK was installed:
adk run mysolution/
# ... but if you get: -bash: adk: command not found"
# 2. Call ADK cli script through UV to avoid python install nightmares.
uv run adk run mysolution/

Попробуйте использовать его в запросе выше.

Скорее всего, он не сможет назвать точные даты. Нам нужно научить его определять дату!

Для веб-версии:

1. uv run adk web . – запуск всех агентов в этой папке. Вы хотите, чтобы он указывал на подпапку mysolution/.
2. Нажмите на значок mysolution/ в правом верхнем углу (см. изображение справа).
3. Задайте вопрос в текстовом или голосовом формате, используя лакмусовый запрос.

Обратите внимание, что вам нужно вызвать adk web из верхней папки, в зависимости от версии CLI.

Вот возможное решение с частичной галлюцинацией даты. Обратите внимание, что работают три из пяти ссылок для бронирования. Неплохо.

5. Шаг 2. Добавьте инструмент now()

Добавьте эту функцию в файл agent.py непосредственно перед определением root_agent:

from datetime import datetime

def now() -> dict:
    """Returns the current date and time."""
    my_datetime = ... # Ask Gemini CLI to help you!
    return {
        "status": "success",
        "current_time": my_datetime
    }

Обновите определение агента, чтобы включить инструмент:

  # file XXX.py

  root_agent = Agent(
        name="..",
        model="..",
        instruction="..",
        tools=[now] # <== This is the only line you want to add.
    )

Запустите его снова и задайте тот же вопрос. Теперь он должен знать дату (хорошо) и не иметь точных данных об отелях (плохо).

Вы также можете протестировать его с помощью следующего кода:

# Let's pretend we're in Milan. This should call the tool
# and respond correctly (possibly with some TZ math issues)
echo "What time is it in Milan?" | uv run adk run mysolution/

6. Шаг 3. Пора переключиться: google_search

google_search. Это позволяет нашему агенту получать информацию из интернета в реальном времени.

Примечание. Модели 🚨 gemini-2.x не могут одновременно использовать Google Поиск и пользовательские инструменты (см. проблему № 969), поэтому мы заменим now() на google_search. Подробную информацию можно найти в файле ISSUES.md.

Ваша задача – изменить агента из шага 2. Вместо инструмента now вы импортируете и будете использовать инструмент google_search из библиотеки ADK.

# Full Code: `steps/step03_search/agent.py`
# Remember to REMOVE the now() tool here. See above why.
from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="travel_agent",
    model="gemini-2.5-flash",
    tools=[google_search],
    instruction="""You are a travel agent.
Your job is to help the user plan a trip.
You have access to a search engine.
If you don't know the answer, you can use the search engine.
When you are done, reply with "DONE".""",
)

Как запустить

Выполните те же действия, что и на шаге 1.

Только для экспертов. Для более сложной интеграции (с одновременным использованием google_search и now) проверьте код в steps/step03b_search_and_tool/agent.py и запустите его с помощью make run-step3b. Это необязательно.

7. Шаг 4. Более сложный инструмент: MCP

Теперь, когда мы рассмотрели как пользовательские, так и встроенные инструменты, давайте перейдем к более мощному решению: шаблону Модель как инструмент с использованием протокола контекста модели (MCP).

Чтобы вы могли сосредоточиться на мощных возможностях MCP, мы снова заменим предыдущий инструмент (google_search). Мы снова представим простой инструмент now, который будет работать вместе с инструментом airbnb_mcp. Это показывает, как агент может использовать несколько совместимых инструментов (в данном случае FunctionTool и MCPToolset) для выполнения сложных задач.

# Full Code: steps/step04_mcp/agent.py
# ... Imports as before
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

def now() -> dict:
    # ... as before

# Configure the Airbnb MCP Toolset
airbnb_mcp = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command='npx',
            args=["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"],
        ),
    )
)

root_agent = Agent(
    name="travel_mcp",
    model="gemini-2.5-flash",
    instruction="You are a helpful travel assistant. You can find accommodation using Airbnb, and have access to the current time.",
    tools=[now, airbnb_mcp],
)

Как запустить

Для этого шага в системе должен быть установлен npx. В остальном все так же, как и в предыдущем случае.

Предупреждения и ошибки

1. Если вы видите ошибку ограничения robots.txt, вы можете добавить в MCP директиву игнорирования robots.txt. Подробную информацию вы найдете в документации: https://github.com/openbnb-org/mcp-server-airbnb.
2. Если вы получили ошибку timeout (5 секунд – слишком мало для получения ответов от Airbnb), ознакомьтесь с документацией ADK, чтобы узнать, как увеличить время ожидания, например до 30 секунд. Или используйте Gemini CLI. Обратите внимание, что 3 декабря 2025 г. Cloud Shell выдал мне ошибку тайм-аута. Я исправил ее, но ошибки продолжали появляться, пока я не принудительно установил предыдущую версию: args=["-y", "@openbnb/mcp-server-airbnb@0.1.2", "--ignore-robots-txt"].

8. 🏅 Этап 1 пройден!

🏅 Поздравляем! 🏅 Теперь вы эксперт по ADK! Вы завершили первую часть семинара и успешно создали и протестировали ИИ-агентов с собственными, встроенными и расширенными инструментами MCP. Теперь вы готовы создавать собственных агентов с помощью Google Agent Development Kit.

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

Теперь добавим дополнительную функциональность с помощью Gemini CLI.

9. 🏅 Этап 2. Вайб-кодинг с помощью ADK и Gemini CLI

Теперь перейдем к самой интересной части семинара.

1. Убедитесь, что вы git commitсохранили код в надежном месте. Вы можете создать форк исходного кода или ветку. Не волнуйтесь, Gemini CLI отлично справится с этой задачей.
2. Найдите 💡 идею, которую хотите реализовать. Вы можете выбрать одну из идей ниже, придумать свою или попросить Gemini изучить документацию в rag/ и предложить несколько идей.
3. Выполните необходимые условия, чтобы Gemini мог читать документы ADK.

💡 Идеи

1. 🟢 [Легко] Вы полиглот? Вы хотите пожертвовать go, java или TypeScript? Рефакторинг существующего кода очень прост. Просто скачайте нужный ADK и попросите Gemini CLI выполнить перевод.
2. 🟢 [Просто] Добавьте эмодзи или укажите формат вывода, который вам нравится (например, таблица с эмодзи отеля, за которым следует цена, а затем эмодзи с 1–5 звездами на основе 🌕🌕🌕🌗🌑, чтобы также делать половинки!).
3. 🟢 [Просто] Измените запрос, чтобы научить ИИ искать то, что вам нужно (например, можно ли с животными, не первый этаж, тихий район, рядом с остановками общественного транспорта и т. д.), и протестируйте его. Добавь личную оценку, например "оценка от YOUR_NAME от 1 до 10", на основе вышесказанного и отсортируй по этой оценке.
4. 🟢 [easy] Any Operator in the room? Разверните в Cloud Run. или Vertex AI Agent Engine. Знаете ли вы, что можете интегрировать этого агента и вызывать его напрямую из нового Gemini Enterprise?
5. 🟢 [Просто] Интегрируйте adk run с 🍌 NanoBanana MCP. Требуется ключ Gemini API. Здесь вы сможете создавать изображения, но не визуализировать их. Ниже приведен более сложный вариант.
6. 🟡 [Средний] Создайте субагента, который будет выполнять HotelSearch, и создайте BudgetAgent или LocationAgent, который сможет повторно проверять и перебирать отели с учетом ваших требований к местоположению, например "не более X км от МЕСТОПОЛОЖЕНИЯ". Если API не позволяет этого сделать, может потребоваться несколько итераций с помощью Google Поиска. Примечание. Вы можете использовать Gemini CLI.
7. 🟡 [Средний] Реализуйте AirbnbReviewAgent, который будет анализировать отзывы и обобщать положительные и отрицательные моменты в нескольких пунктах с цветовой кодировкой для одного или нескольких отелей, найденных в результате поиска. У вас уже есть два ингредиента (Google Поиск и MCP Airbnb). Теперь вам нужно подключить их к основному агенту и, возможно, придумать какой-то протокол для их взаимодействия.
8. 🟡 [Средний] Интеграция с A2A. Сделайте его A2A-агентом! И снова спросите Gemini CLI.
9. 🔴 [Сложно] Вы можете интегрировать Авиабилеты или другие функции MCP, чтобы создать многофункциональное туристическое агентство.
10. 🔴 [Сложно] Интегрируйте ADK web с 🍌 NanoBanana MCP. Это сложнее, чем предыдущий шаг. Советы можно найти на странице https://github.com/palladius/ai-friendly-agents/issues/11. На это у автора ушло три часа общения с Gemini CLI и Gemini 3, а также чтения документации и кода из rag/.

Нужны идеи?

1. Идеи можно найти в официальном руководстве по ADK.
2. Попросите Gemini CLI найти идеи в документации по адресу rag/. Возможный запрос: Is there a feature in here which seems very succulent to you? Give me 3 proposals and let's implement together the one I choose.

Предварительные требования для RAG в ADK

Чтобы написать код для функции, рекомендуем скачать весь ADK python ADK (примечание: его можно легко адаптировать к вашему любимому языку, например Java или Go).

Код распространяется по лицензии ./rag, и его можно скачать с помощью ./download-adk.sh.

Поскольку папка rag указана в файле .gitignore, убедитесь, что файл .gemini/settings.json содержит следующее:

{
 "context": {
   "includeDirectories": ["rag"]
 }
}

Зачем? Мы хотим, чтобы Gemini мог читать эти файлы, но они не попадали в git. Технически вы также можете показать все файлы .gitignore, установив для context.fileFiltering.respectGitIgnore значение false, но это откроет много мусора node_modules/ и __pycache__/, поэтому предпочтительным вариантом является явное включение папки.

10. Дальнейшие действия

Любознательность. Этот семинар был создан с помощью Gemini CLI. Если вам интересно, как я это сделал, посмотрите файлы GEMINI.md и WORKSHOP_PLAN.md в этой папке.

Выводы

Мы узнали, как использовать ADK с Gemini CLI.

Дополнительные сведения

• Ознакомьтесь с двумя официальными практическими работами по Antigravity:
  • Начало работы с Google Antigravity
  • Работа с Google Antigravity
  • Создание и развертывание в Google Cloud с помощью Antigravity
• Идеи можно найти в официальном руководстве по ADK.