Ускоренный курс ADK — от новичка до эксперта

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

Добро пожаловать на мастер-класс ADK — ваше путешествие в мир многоагентных систем

Вы готовы шагнуть в захватывающий мир агентов на основе искусственного интеллекта. Забудьте о простых чат-ботах, которые просто отвечают на вопросы. Мы углубляемся в изучение Agent Development Kit (ADK) для создания сложных автономных систем, способных рассуждать, планировать и использовать инструменты для выполнения сложных задач.

Вся эта мастер-класс-лаборатория будет практическим занятием, и я покажу вам два основных блокнота Colab , которые содержат весь код и примеры для наших сессий. Colab 1: Инструменты и память , Colab 2: Мультиагенты

К концу этого урока вы сможете:

• Создайте своего первого ИИ-агента : пройдите путь от нуля до полностью функционального агента, который может понимать потребности пользователя, использовать такие инструменты, как Google Поиск, и генерировать подробные, полезные ответы.
• Освойте пользовательские инструменты : раскройте весь потенциал агентов, подключив их к собственным функциям и API. Вы научите своего агента получать данные в режиме реального времени, например, прогнозы погоды.
• Создавайте многоагентные системы : изучите шаблон «Агент как инструмент» , революционную концепцию, в которой агенты делегируют задачи другим специализированным агентам, создавая команду экспертов по ИИ, работающих вместе.
• Организуйте сложные рабочие процессы : выходите за рамки простого делегирования и осваивайте такие сложные шаблоны, как маршрутизаторы , последовательные цепочки , циклы и параллельное выполнение, чтобы создавать надежные, эффективные и интеллектуальные приложения, способные обрабатывать практически любые запросы.
• Дайте своим агентам память : поймите важную роль разговорной памяти, которая позволит вашим агентам отвечать на уточняющие вопросы, учиться на обратной связи и беспрепятственно выполнять многоэтапные задачи.

Давайте начнем! 🚀

2. Настройте ключ GCP и Gemini API

Настройка вашего проекта GCP и ключа API Gemini

Для работы наших ИИ-агентов нам нужны две вещи: проект Google Cloud, который станет основой, и ключ API Gemini для доступа к мощным моделям Google.

Шаг 1: Включите платежную учетную запись

• Активируйте свой платёжный аккаунт с 5 долларами на балансе, которые понадобятся вам для развёртывания. Убедитесь, что он связан с вашим аккаунтом Gmail .

Кредитная карта и оплата не требуются — вы получите 5 долларов бесплатно. Это займёт меньше 2 минут: просто введите своё имя и подтвердите получение кредита.

Шаг 2: Создайте новый проект GCP

• Перейдите в Google Cloud Console и создайте новый проект.

• Перейдите в Google Cloud Console и создайте новый проект.
• Откройте левую панель, нажмите Billing , проверьте, связан ли счет выставления счетов с этой учетной записью GCP.

Если вы видите эту страницу, проверьте manage billing account , выберите Google Cloud Trial One и подключитесь к нему.

Шаг 3: Сгенерируйте ключ API Gemini

Прежде чем вы сможете получить ключ, вам нужно его иметь.

• Перейдите в Google AI Studio: https://aistudio.google.com/
• Войдите в систему, используя свою учетную запись Gmail .
• Нажмите кнопку «Получить ключ API» , которая обычно находится на левой навигационной панели или в правом верхнем углу.
• В диалоговом окне «Ключи API» нажмите «Создать ключ API в новом проекте».
• Выберите новый созданный вами проект, в котором настроена учетная запись для выставления счетов.
• Для вас будет сгенерирован новый ключ API. Немедленно скопируйте его и временно сохраните в безопасном месте (например, в менеджере паролей или в заметке). Это значение вам понадобится на следующих этапах.

3. Сессия 1: Ваш первый агент с Runner

Начнём с основ. Здесь мы создаём нашего первого простого агента — day_trip_agent . Его задача — сформировать маршрут однодневной поездки на основе запроса пользователя с учётом бюджета. В этом примере представлены три основных компонента любого взаимодействия с агентом в ADK:

• Агент : центральный мозг операции. Он определяется своими инструкциями (личностью и миссией), используемой моделью искусственного интеллекта (например, «Джемини») и инструментами, к которым он имеет доступ.
• Сеанс : память разговора. Хранит историю взаимодействий (сообщения пользователей и ответы агентов), обеспечивая непрерывный диалог.
• Runner : движок, выполняющий задачу. Он принимает агента и сеанс, обрабатывает новый запрос пользователя и организует шаги для генерации ответа.

➡️ Где это найти в блокноте

👉 Это соответствует ячейкам в Части 1: Ваш первый агент — Джинн однодневных поездок 🧞 .🌟

• Определение агента : найдите функцию create_day_trip_agent() . Именно здесь определяется агент. Обратите внимание на подробную строку инструкций — это подсказка, которая сообщает агенту, как себя вести. Мы также предоставляем ему первый инструмент: Поиск Google.
• Вспомогательная функция : Здесь определена вспомогательная функция run_agent_query() . Мы будем использовать эту утилиту на протяжении всего блокнота для упрощения выполнения запросов.
• Тестовый запуск : Функция run_day_trip_genie() имитирует запрос пользователем «доступного» и «расслабляющего» однодневного путешествия. Агент использует полученные инструкции и инструмент поиска Google для поиска подходящих мест и создания маршрута в формате Markdown.

➡️ Действие : Изучите запрос инструкции для day_trip_agent . Обратите внимание, как запрос «доступной» поездки в тестовом запросе напрямую связан с правилом агента «Учитывать бюджет».

4. Сессия 2: Пользовательские инструменты 🛠️

Несмотря на всю мощь Google Поиска, истинный потенциал ИИ-агентов раскрывается при подключении их к собственным уникальным источникам данных, API или пользовательской логике. В этом разделе мы создадим собственный инструмент на основе простой функции Python.

Самая важная часть инструмента-функции — это его строка документации. ADK автоматически анализирует её, чтобы понять, что делает инструмент, какие параметры он принимает (Args) и что он возвращает (Returns). Большая языковая модель (LLM) считывает это описание, чтобы решить, когда и как использовать инструмент.

➡️ Где это найти в блокноте

👉 Это соответствует ячейкам в разделе 2.1 Простой инструмент-функция: вызов API погоды в реальном времени . 🌟

• Определение инструмента : Функция get_live_weather_forecast(location: str) — ядро ​​нашего инструмента. Она принимает название города, вызывает общедоступный API Национальной метеорологической службы и возвращает словарь с температурой и прогнозом.
• Определение агента : Агент погоды (weather_agent) создаётся и оснащается нашим новым инструментом путём передачи tools=[get_live_weather_forecast] во время его инициализации. Инструкции агента явно указывают ему использовать этот инструмент перед предложением мероприятий на свежем воздухе.
• Тестовый запуск : запрос «Я хочу отправиться в поход возле озера Тахо. Какая там погода?» напрямую заставляет агента использовать инструмент get_live_weather_forecast поскольку этого требуют его инструкции.

➡️ Действие : Ознакомьтесь с документацией для функции get_live_weather_forecast и инструкцией для weather_agent . Обратите внимание на прямую связь между ними.

5. Сессия 3: Агент как инструмент 🧑‍🍳

Зачем создавать единого, монолитного агента, если можно создать команду специалистов? Шаблон Agent-as-a-Tool — это эффективный способ создания сложных систем, в которых основной агент, часто называемый «Оркестратором» или «Маршрутизатором», делегирует задачи другим, более узкоспециализированным агентам.

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

➡️ Где это найти в блокноте

👉 Это соответствует ячейкам в разделе 2.2 Агент как инструмент: консультация специалиста 🧑‍🍳 .🌟

В этом примере создается сложная многоуровневая система агентов:

• Специалисты :
  • food_critic_agent : узкоспециализированный агент, который только дает рекомендации по ресторанам.
  • db_agent : фиктивный агент, который делает вид, что запрашивает информацию об отелях из базы данных.
  • concierge_agent : агент среднего звена, выполняющий функции вежливого консьержа. Важно отметить, что у него есть собственный инструмент — food_critic_agent .
• Оркестратор ( trip_data_concierge_agent ): это агент верхнего уровня, с которым взаимодействует пользователь. Его инструкции делают его «главным планировщиком путешествий», и ему предоставлены два инструмента для вызова других агентов:
  • call_db_agent : Функция, которая вызывает db_agent .
  • call_concierge_agent : Функция, которая вызывает concierge_agent .
• Поток : тестовый запуск в run_trip_data_concierge() демонстрирует полную цепочку делегирования.
  • Пользователь запрашивает у организатора информацию о гостинице и ближайшем ресторане.
  • Инструкции оркестратора говорят ему сначала использовать инструмент call_db_agent для получения данных об отелях.
  • Затем оркестратор использует инструмент call_concierge_agent для получения рекомендации.
  • Получив запрос, concierge_agent использует собственный инструмент food_critic_agent , чтобы получить представление о ресторане.

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

➡️ Действие : Проследите поток выполнения в тестовом прогоне в run_trip_data_concierge() . Обратите внимание, как распечатки TOOL CALLED отображают цепочку делегирования от оркестратора к специалистам. Это последовательная цепочка команд.

6. Сессия 4: Память агента 🧠

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

При использовании одного и того же объекта сеанса для нескольких последовательных запросов агент может «видеть» всю историю разговора. Это позволяет ему обрабатывать уточняющие вопросы, корректировать свои действия на основе обратной связи и планировать многоэтапные задачи.

➡️ Где это найти в блокноте

👉 Это соответствует ячейкам в Части 3: Агент с памятью — Адаптивный планировщик 🗺️ . 🌟

• Определение агента : Функция create_multi_day_trip_agent() определяет агента, предназначенного для поэтапного планирования поездки. В его инструкциях особое внимание уделяется запоминанию контекста, обработке отзывов и планированию по одному дню за раз.

Сценарий 3a: Агент С памятью (✅)

Этот тест запускается в функции run_adaptive_memory_demonstration() .

• Создается один trip_session , который используется повторно в течение трех последовательных ходов.
• Ход 1 : Пользователь инициирует план двухдневной поездки.
• Ход 2 : Пользователь даёт обратную связь («Я не большой поклонник замков»). Поскольку агент помнит ход 1, он понимает, какую часть плана нужно изменить, и предлагает альтернативный вариант.
• Ход 3 : Пользователь подтверждает изменение и запрашивает следующий шаг. Агент запоминает всё и переходит к планированию Дня 2.

Сценарий 3б: Агент БЕЗ памяти (❌)

Этот тест запускается в функции run_memory_failure_demonstration() .

Это демонстрирует критическую важность управления сеансом, совершая преднамеренную ошибку. Для каждого хода создаётся новый сеанс .

• Ход 1 : Пользователь инициирует поездку в сеансе session_one. Агент отвечает правильно.
• Ход 2 : Пользователь просит запланировать День 2, но запрос отправляется в совершенно новом сеансе session_two. Поскольку у этого нового сеанса нет истории, агент в замешательстве. У него амнезия! Он не знает, какая поездка планируется.

Действие : Сравните ответы агента в run_adaptive_memory_demonstration() и run_memory_failure_demonstration() . Это самая важная концепция в блокноте: для одного непрерывного диалога требуется один непрерывный сеанс.

7. Сессия 5: Агент маршрутизатора 🚏

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

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

Например, запрос о «лучших суши» должен быть направлен foodie_agent, а вопрос о «концертах на этих выходных» должен быть обработан weekend_guide_agent .

➡️ Где это найти в блокноте:

👉 Эта концепция является центральной для всего блокнота, но впервые она представлена ​​в Части 1: Многоагентный хаос — последовательные рабочие процессы 🧠→🤖→🤖 🌟

• Определения агентов : в ячейке кода определены несколько специализированных агентов (day_trip_agent, foodie_agent, Transportation_agent) и, что самое главное, агент-маршрутизатор. Обратите особое внимание на запрос инструкции для агента-маршрутизатора: в нём явно указано возвращать только имя наиболее подходящего агента для выполнения задания.
• Логика выполнения : Функция run_sequential_app демонстрирует, как сначала вызвать router_agent для получения решения (chosen_route), а затем использовать это решение в блоке if/elif для выполнения соответствующего специализированного агента.

8. Сессия 6: SequentialAgent ⛓️

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

ADK предоставляет простой и эффективный способ управления этим процессом с помощью SequentialAgent. Это специальный агент рабочего процесса, который выполняет список подагентов в предопределённом порядке.

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

➡️ Где это найти в блокноте:

👉 Об этом рассказывается в части 2 (метод ADK): многоагентный хаос с SequentialAgent 🧠→⛓️→🤖 . 🌟

• Рефакторинг агента: в первой ячейке кода этого раздела обратите внимание на ключевые изменения в foodie_agent и transportation_agent :
  • У foodie_agent теперь есть output_key="destination" . Это указывает ADK сохранить окончательный ответ в переменной destination в общем состоянии.
  • У transportation_agent теперь есть плейсхолдер {destination} в строке запроса инструкции. ADK автоматически добавляет значение из общего состояния в этот плейсхолдер.
• Определение рабочего процесса : find_and_navigate_agent определяется как SequentialAgent, а его подагенты устанавливаются в [ foodie_agent , transportation_agent ], что гарантирует их запуск в точном порядке.
• Упрощённое выполнение : обратите внимание на функцию run_sequential_app в этом разделе. Сложная логика if/elif исчезла! find_and_navigate_agent теперь рассматривается как единый вызываемый блок, а ADK автоматически обрабатывает внутренние последовательные шаги.

9. Сессия 7: LoopAgent 🔁

Не все проблемы имеют простое и быстрое решение. Иногда нам нужно предложить решение, критически его рассмотреть и доработать, пока оно не будет соответствовать определённым ограничениям.

Для этого в ADK предусмотрен LoopAgent . Этот агент рабочего процесса многократно выполняет последовательность подагентов до тех пор, пока не будет выполнено определённое условие. Это идеально подходит для создания «перфекционистских» агентов, способных планировать, критиковать и улучшать свою работу.

На диаграмме показано, Planner Agent сначала создаёт план. Затем мы входим в LoopAgent . Critic Agent проверяет план. Если план некорректен, Refiner Agent создаёт новую версию, и цикл повторяется. Если план верный, Refiner Agent вызывает инструмент exit_loop и возвращает окончательный, проверенный план.

➡️ Где это найти в блокноте:

👉 Это объясняется в разделе «Итеративные идеи с LoopAgent» 🧠→🔁→🤖 . 🌟

• Основные агенты : рабочий процесс использует planner_agent , critic_agent и refiner_agent .
• Определение цикла : refinement_loop определяется как LoopAgent, который организует critic_agent и refiner_agent и sets max_iterations=3 .
• Условие выхода : цикл завершается, когда critic_agent одобряет план, что приводит к тому, что refiner_agent вызывает пользовательский инструмент exit_loop .

10. Сессия 8: ParallelAgent ⚡️

Эффективность — ключ к успеху. Если пользователь запрашивает сразу несколько разрозненных фрагментов информации, выполнение этих запросов по одному будет медленным.

Решение — ParallelAgent . Этот агент рабочего процесса выполняет список подагентов одновременно. После завершения всех параллельных задач их результаты можно собрать и синтезировать в единый комплексный ответ.

На этой диаграмме показано, как ParallelAgent обрабатывает один запрос и разделяет его на три параллельных потока. museum_finder , concert_finder и restaurant_finder выполняются одновременно. После завершения всех трёх процессов их индивидуальные результаты (сохранённые в общем состоянии) объединяются и передаются конечному агенту синтеза, который объединяет их в один ответ.

➡️ Где это найти в блокноте:

👉 Этот рабочий процесс подробно описан в разделе Параллельное питание с ParallelAgent 🧠→⚡️→🤖🤖🤖 . 🌟

• Специализированные агенты : определены три специализированных агента, каждый из которых имеет уникальный output_key (например, museum_result).
• Параллельный рабочий процесс : parallel_research_agent определяется как ParallelAgent, а три агента поиска указаны в качестве его подагентов.
• Шаг синтеза : После параллельного шага последний агент синтеза собирает все результаты из общего состояния, используя заполнители ( {museum_result} , {concert_result} и т. д.) для форматирования аккуратного резюме.

11. Приложение: ADK Web — 🍎 Для Mac/Linux

Это руководство поможет вам настроить и запустить ADK Day Trip Planning Agent на вашем локальном компьютере.

Предпосылки

• Python 3.8 или выше
  • Python 3.9+ : устанавливает google-adk==1.5.0 (последняя версия с полным набором функций)
  • Python 3.8 : устанавливает google-adk==0.3.0 (совместимую версию)
• API-ключ Google AI Studio
• подключение к Интернету

Шаг 1: Клонирование репозитория

Откройте Терминал и выполните:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Шаг 2: Настройка виртуальной среды и установка зависимостей

Вариант А: Автоматическая настройка (рекомендуется)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

Вариант Б: Ручная настройка

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Шаг 3: 🔥 ВАЖНО — Создайте переменные среды

⚠️ Не пропускайте этот шаг! Создайте файл .env в каталоге agent/ :

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

Добавьте эти строки в файл:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 ВАЖНО : Замените your_actual_api_key_here на ваш фактический ключ API!

Шаг 4: Активируйте виртуальную среду (если она еще не активна)

source .adk_env/bin/activate

В начале командной строки терминала вы должны увидеть (.adk_env) .

Шаг 5: Запустите веб-интерфейс ADK

adk web

Шаг 6: Откройте браузер.

1. Откройте браузер и перейдите по URL-адресу, указанному в терминале (обычно http://localhost:8000 ).
2. В раскрывающемся списке слева вверху выберите agent .
3. Начните общение с вашим агентом по планированию однодневной поездки!

Вы увидите примерно такой разговор:

Деактивация среды

Когда вы закончите работу с проектом:

deactivate

Эта команда работает одинаково как на Mac/Linux, так и на Windows. Вы заметите, что префикс (.adk_env) исчезнет из командной строки терминала.

Устранение неполадок на Mac

• Python не найден : используйте python3 вместо python
• Отказано в доступе : выполните chmod +x setup_venv.sh перед запуском скрипта.

12. Приложение: ADK Web — 🪟 Для пользователей Windows

Это руководство поможет вам настроить и запустить ADK Day Trip Planning Agent на вашем локальном компьютере.

Предпосылки

• Python 3.8 или выше
  • Python 3.9+ : устанавливает google-adk==1.5.0 (последняя версия с полным набором функций)
  • Python 3.8 : устанавливает google-adk==0.3.0 (совместимую версию)
• API-ключ Google AI Studio
• подключение к Интернету

Шаг 1: Клонирование репозитория

Откройте командную строку или PowerShell и выполните:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Шаг 2: Настройка виртуальной среды и установка зависимостей

Вариант А: Автоматическая настройка (рекомендуется)

# Run the setup script in Command Prompt
setup_venv.bat

Вариант Б: Ручная настройка

Для командной строки:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Для PowerShell:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Шаг 3: 🔥 ВАЖНО — Создайте переменные среды

⚠️ Не пропускайте этот шаг! Создайте файл .env в каталоге agent/ :

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

Добавьте эти строки в файл:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 ВАЖНО : Замените your_actual_api_key_here на ваш фактический ключ API!

Шаг 4: Активируйте виртуальную среду (если она еще не активна)

Командная строка:

.adk_env\Scripts\activate

PowerShell:

.adk_env\Scripts\Activate.ps1

В начале приглашения вы должны увидеть (.adk_env) .

Шаг 5: Запустите веб-интерфейс ADK

adk web

Шаг 6: Откройте браузер.

1. Откройте браузер и перейдите по URL-адресу, указанному в терминале (обычно http://localhost:8000 ).
2. В раскрывающемся списке слева вверху выберите agent .
3. Начните общение с вашим агентом по планированию однодневной поездки!

Устранение неполадок Windows

• Ошибка политики выполнения PowerShell : Run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Вы увидите примерно такой разговор:

Деактивация среды

Когда вы закончите работу с проектом:

deactivate

Эта команда работает одинаково как на Mac/Linux, так и на Windows. Вы заметите, что префикс (.adk_env) исчезнет из командной строки терминала.