Шаблон агента ADK с памятью и MCP

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

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

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

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

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

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

Начнём! 🚀

2. Настройка: Получите свой API-ключ

Настройка ключа API Google AI Studio

Этот практический урок полностью работает с использованием бесплатного ключа API Google AI Studio. Не требуется ни проект Google Cloud, ни учетная запись для выставления счетов, ни кредиты — каждый урок, включая Memory (урок 6) и MCP (урок 7), выполняется локально с использованием вашего ключа. Каждый участник использует свой собственный ключ, поэтому квота API предоставляется на одного человека, а не распределяется между всеми.

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

• Python 3.9 или выше (для проверки используйте python3 --version )
• Учетная запись Google (для создания ключа AI Studio)
• Терминал — подойдет как ваш локальный компьютер , так и Cloud Shell.
• ~10 минут

Для работы наших ИИ-агентов нам необходим API-ключ Gemini из Google AI Studio. Это самый быстрый способ начать работу.

Шаг 1 — Получите свой API-ключ Gemini в AI Studio (1 мин)

1. Откройте https://aistudio.google.com/app/apikey в новой вкладке браузера.
2. Войдите в систему, используя свою учетную запись Google.
3. Нажмите кнопку "Создать ключ API" (в правом верхнем углу).
4. Открывается диалоговое окно с выпадающим списком проектов:

• Если у вас уже есть созданный ранее проект Google: выберите его и нажмите «Создать ключ API в существующем проекте».
• Если проекта нет в списке: нажмите «Создать проект» .

5. Скопируйте появившийся ключ API . Он начинается с AIza... и состоит примерно из 40 символов.

✏️ Вставьте его в надежное место — он понадобится вам на шаге 4 ниже.

Относитесь к ключу API как к паролю. Не вставляйте его в публичные чаты, скриншоты и не добавляйте в публичный репозиторий GitHub.

Шаг 2 — Клонирование репозитория (1 мин)

👉💻 Откройте терминал (или Cloud Shell) и клонируйте репозиторий с учебным материалом:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Шаг 3 — Создание виртуальной среды и установка зависимостей

👉💻 Создайте и активируйте виртуальное окружение с именем .adk_env , затем установите зависимости:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

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

Шаг 4 — 🔥 ВАЖНО: Добавьте свой API-ключ

⚠️ Не пропускайте этот шаг! Создайте файл .env в корневой папке adk_tutorial . Этот файл обеспечивает работу всех сессий в данном практическом руководстве — сессии ADK Web (1–5) и сессии командной строки Memory и MCP (6–7) будут считывать его автоматически.

👉💻 Создайте файл .env с вашим ключом (замените your_actual_api_key_here на ключ из шага 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Теперь ваш ~/adk_tutorial/.env должен содержать:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 ВАЖНО : Замените your_actual_api_key_here на ваш фактический API-ключ из Шага 1 (он начинается с AIza... ).

⚠️ Убедитесь, что GOOGLE_GENAI_USE_VERTEXAI установлен в FALSE . Это указывает ADK на необходимость аутентификации с помощью вашего ключа API Google AI Studio, а не Vertex AI.

✅ Контрольная точка: У вас есть файл .env по адресу ~/adk_tutorial/.env содержащий ваш ключ AIza... , и в командной строке терминала отображается (.adk_env) . Вы готовы к сборке агентов!

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

Откройте веб-версию ADK, выполнив следующую команду:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

После выполнения команд в терминале должен отобразиться вывод, указывающий на запуск веб-сервера ADK, примерно такой:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Затем откройте в браузере адрес http://localhost:8000, чтобы получить доступ к пользовательскому интерфейсу разработчика ADK .

Запускаете приложение в Cloud Shell вместо локального доступа? Щелкните значок предварительного просмотра веб-страницы на панели инструментов Cloud Shell (обычно в правом верхнем углу), выберите «Изменить порт» , установите порт на 8000 и нажмите «Изменить и просмотреть» . Cloud Shell откроет пользовательский интерфейс разработчика ADK в новой вкладке браузера.

👉 Ваш ритуал призыва завершен, и агент запущен. Интерфейс разработчика ADK в вашем браузере — это ваша прямая связь с Фамильяром.

Выберите своего первого агента. В выпадающем меню в верхней части пользовательского интерфейса выберите a_single_agent .

Здесь вы можете выбрать a_single_agent :

Здесь вы можете увидеть результаты трассировки:

👉 Тестовое задание:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Сессия 2: Агент рабочего процесса: Последовательный агент, Параллельный агент, Циклический агент

Откройте веб-интерфейс ADK, выполнив шаги, описанные в первом сеансе .

Параллельный агент

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

👉 Тестовое задание:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Здесь вы можете выбрать b2_parallel_agent :

Здесь вы можете увидеть результаты трассировки:

Последовательный агент

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

👉 Тестовое задание:

Find a good sushi near Standford and tell me how to get there.

Здесь вы можете выбрать b1_sequential_agent :

Здесь вы можете увидеть результаты трассировки:

Агент петли

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

👉 Тестовое задание:

Plan a trip from Sunnyvale to San Francisco today.

Здесь вы можете выбрать b3_loop_agent :

Здесь вы можете увидеть результаты трассировки:

5. Сессия 3: Пользовательский агент

Откройте веб-интерфейс ADK, выполнив шаги, описанные в первом сеансе .

После открытия веб-интерфейса ADK выберите c_custom_agent из выпадающего списка.

👉 Тестовое задание:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Здесь вы можете выбрать c_custom_agent :

Здесь вы можете увидеть результаты трассировки:

6. Сессия 4: Шаблон оркестратора — Агент маршрутизации

Откройте веб-интерфейс ADK, выполнив шаги, описанные в первом сеансе .

После открытия веб-интерфейса ADK выберите d_routing_agent из выпадающего списка.

👉 Тестовое задание:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Здесь вы можете выбрать d_routing_agent :

Здесь вы можете увидеть результаты трассировки:

7. Сессия 5: Агент как инструмент

Откройте веб-интерфейс ADK, выполнив шаги, описанные в первом сеансе .

После открытия веб-интерфейса ADK выберите e_agent_as_tool из выпадающего списка.

👉 Тестовое задание:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Здесь вы можете выбрать e_agent_as_tool :

Здесь вы можете увидеть результаты трассировки:

8. Сессия 6: Агент с долговременной памятью

Работает полностью локально. Эта сессия хранит память разговоров в локальной базе данных SQLite (в ~/.adk/ ), поэтому ваши настройки сохраняются после перезапуска без необходимости использования Google Cloud, оплаты или кредитов . Агент считывает ваш ключ AI Studio из файла ~/adk_tutorial/.env созданного вами в процессе настройки.

👉💻 Проверьте свою долговременную память, перейдя в папку и используя средство запуска, чтобы активировать агента:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Тестовое задание:

I like Art and Italian food.

Затем завершите сессию, нажав Ctrl+C . Перезапустите сессию:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Тестовое задание:

Plan a trip to San Francisco based on my preference.

✅ Агент должен вспомнить тему «Искусство и итальянская кухня» из предыдущего сеанса — это долговременная память, работающая между сеансами.

9. Сессия 7: Расширьте возможности своего агента с помощью MCP.

Работает полностью локально. Эта сессия запускает локальный сервер MCP Toolbox, который считывает локальную базу данных SQLite ( destinations.db ) — Google Cloud, оплата или кредиты не требуются. Единственная внешняя загрузка — это бинарный файл MCP Toolbox с открытым исходным кодом.

Шаг 1: Подготовка локальной базы данных

👉💻 Создайте тестовую базу данных в корневом каталоге репозитория:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Это создаст destinations.db в папке ~/adk_tutorial/ .

⚠️ Пример базы данных содержит только четыре города — Париж, Рим, Нью-Йорк и Токио (типы достопримечательностей: достопримечательности, музеи, парки). Запросы, ссылающиеся на другие города (например, Сан-Франциско или Саннивейл), корректно не вернут результатов , поскольку таких строк не существует. Используйте указанные выше четыре города при тестировании этой сессии.

Шаг 2: Установите и запустите сервер MCP Toolbox.

👉💻 Скачайте исполняемый файл MCP Toolbox для вашей операционной системы :

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

после завершения загрузки запустите

chmod +x toolbox

Не уверены, какая у вас модель Mac? Выполните команду uname -m — arm64 = ​​Apple Silicon, x86_64 = Intel. В Windows загрузите файл .../windows/amd64/toolbox.exe и запустите его из PowerShell.

Шаг 3

В одном из терминалов выполните следующую команду (оставьте ее запущенной — агент подключится к ней по адресу http://127.0.0.1:7001 ):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

В другом терминале выполните следующую команду.

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Тестовые подсказки (используйте города, которые есть в базе данных примеров — Париж, Рим, Нью-Йорк или Токио):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

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

• "Соединение отклонено" / агент не находит инструменты: сервер Toolbox в первом терминале не запущен — перезапустите его и убедитесь, что он прослушивает порт 7001 .
• Все запросы возвращают пустые результаты: убедитесь, что вы выполнили Шаг 1 , чтобы файл ~/adk_tutorial/destinations.db существовал, и что в вашей командной строке указан один из четырех городов (Париж, Рим, Нью-Йорк, Токио).
• toolbox: cannot execute binary file в macOS: вы загрузили сборку для Linux — повторно выполните шаг 2 с OS=darwin/arm64 (Apple Silicon) или OS=darwin/amd64 (Intel).