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

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

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

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

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

По завершении этого урока вы сможете:

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

Начнём! 🚀

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

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

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

Шаг 1: Активируйте платежный аккаунт

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

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

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

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

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

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

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

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

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

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

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

• Агент : Главный мозг операции. Его характеристики определяются инструкциями (его личностью и миссией), используемой моделью ИИ (например, Gemini) и доступными ему инструментами.
• Сессия : Память разговора. Она хранит историю взаимодействий (сообщения пользователя и ответы агента), обеспечивая непрерывный диалог.
• Исполнитель : Механизм, выполняющий задачу. Он принимает агента и сессию, обрабатывает новый запрос пользователя и координирует шаги для генерации ответа.

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

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

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

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

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

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

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

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

👉 Это соответствует ячейкам в разделе 2.1 «Простой инструмент FunctionTool: вызов 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() определяет агента, предназначенного для поэтапного планирования поездки. Ее инструкции акцентируют внимание на запоминании контекста, обработке обратной связи и планировании по одному дню за раз.

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

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

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

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

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

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

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

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

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

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

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

Например, запрос о "лучших суши" следует отправлять агенту-гурману, а вопрос о "концертах на этих выходных" — агенту weekend_guide_agent .

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

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

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

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

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

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

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

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

👉 Это рассматривается во второй части (метод ADK): Многоагентный хаос с SequentialAgent 🧠→⛓️→🤖 . 🌟

• Рефакторинг агентов: В первой ячейке кода этого раздела обратите внимание на ключевые изменения в агентах foodie_agent и transportation_agent :
  • Теперь foodie_agent есть output_key="destination" . Это указывает ADK сохранить окончательный ответ в переменную с именем destination в общем состоянии.
  • Теперь в подсказке для команды transportation_agent содержится заполнитель {destination} . ADK автоматически внедряет значение из общего состояния в этот заполнитель.
• Определение рабочего процесса : Агент find_and_navigate_agent определен как SequentialAgent, а его sub_agents установлены на [ 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, а три агента-поисковика перечислены в качестве его sub_agents.
• Этап синтеза : После параллельного этапа заключительный агент синтеза собирает все результаты из общего состояния, используя заполнители ( {museum_result} , {concert_result} и т. д.), чтобы отформатировать аккуратное резюме.

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

В этом руководстве вы узнаете, как настроить и запустить агент планирования однодневных поездок ADK на вашем локальном компьютере.

Предпосылки

• 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: Настройка виртуальной среды и установка зависимостей

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

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

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

# 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. Откройте браузер и перейдите по адресу, указанному в терминале (обычно 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 на вашем локальном компьютере.

Предпосылки

• 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: Настройка виртуальной среды и установка зависимостей

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

# Run the setup script in Command Prompt
setup_venv.bat

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

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

# 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. Откройте браузер и перейдите по адресу, указанному в терминале (обычно http://localhost:8000 ).
2. В выпадающем списке в левом верхнем углу выберите agent .
3. Начните общение с вашим агентом по планированию однодневных поездок!

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

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

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

Деактивация окружающей среды

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

deactivate

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