1. Введение
В этом практическом занятии вы шаг за шагом создадите своего первого ИИ-агента, используя комплект разработки агентов Google (ADK) и Gemini. Вы создадите базового агента для написания блогов, который планирует и пишет контент, демонстрируя основные концепции рассуждения и действия.
Что вы будете делать
- Настройте среду разработки для ADK.
- Создайте многоагентную систему, включающую планировщик и записыватель.
- Запустите агент локально и взаимодействуйте с ним через веб-интерфейс ADK.
Что вам понадобится
- Веб-браузер, например Chrome .
- На вашем компьютере должен быть установлен Python 3.10 или более поздней версии.
- Ключ API Google AI Studio.
Этот практический семинар предназначен для разработчиков всех уровней, включая начинающих.
Ориентировочная продолжительность: 30 минут.
2. Визуальное руководство: Что такое агенты искусственного интеллекта?
Прежде чем приступить к разработке, давайте быстро разберемся, что такое агенты искусственного интеллекта и какие общие закономерности они используют.
Что такое ИИ-агент?
На самом простом уровне, агент — это программное обеспечение, которое не просто отвечает, но и может принимать решения и предпринимать действия. Вместо того чтобы генерировать один ответ, как традиционный чат-бот, он анализирует ваш запрос, определяет необходимые шаги, возможно, вызывает API, запускает код, анализирует результат и затем решает, что делать дальше.
Одно из наиболее ясных объяснений содержится в исследовательской работе ReAct: Synergizing Reasoning and Acting in Language Models . Идея, изложенная в этой работе, проста, но эффективна: языковые модели не должны просто генерировать текст за один раз. Они могут фактически рассуждать шаг за шагом, выполнять действие, например, вызывать инструмент или API, наблюдать за результатом, а затем решать, что делать дальше.
Этот цикл рассуждений, действий, наблюдений и корректировок лежит в основе работы современных агентов искусственного интеллекта. И он соответствует определению Google Cloud: системы, обладающие способностью к рассуждениям, планированию и памяти, с достаточной автономностью для адаптации и принятия решений от имени пользователя.
Три модели поведения агентов
Не все агенты ведут себя одинаково. Полезно рассматривать их в рамках трех основных моделей:
- Последовательные агенты : они работают шаг за шагом, как на конвейере: шаг 1, затем шаг 2, затем шаг 3. Они предсказуемы, но негибкие.
- Реактивные агенты : они принимают решения в моменте. Они оценивают текущую ситуацию и спрашивают: «Что мне делать дальше?» Возможно, инструмент А в один момент, инструмент Б в другой. Они гибкие, но не планируют наперед.
- Агенты, склонные к обдуманному планированию : они делают паузу, чтобы набросать план, а затем приступают к его реализации. Представьте себе бронирование поездки — вы не просто покупаете билет на самолет наугад, вы выбираете даты, отели, упорядочиваете этапы, а затем следуете всем правилам.
Какой из этих вариантов «правильный»? Это зависит от задачи. Для простых, предсказуемых потоков подходит последовательный подход. Для динамических задач лучше подходит реактивный подход. Для многоэтапных целей с зависимостями нужны агенты планирования.
В этой лабораторной работе мы создаём агента, ориентированного на обдумывание и планирование , который сначала составляет план, а затем пишет пост в блоге!
3. Прежде чем начать
Создайте учетную запись и проект в Google Cloud.
Для развертывания агента в Google Cloud Run в дальнейшем в рамках этой лабораторной работы вам потребуется учетная запись Google Cloud и проект с включенной функцией выставления счетов.
- Войдите в консоль Google Cloud . Создайте новый проект или используйте существующий. Если у вас еще нет учетной записи Google, вам необходимо ее создать .
- Далее вам потребуется включить оплату в консоли Cloud, чтобы использовать облачные ресурсы. Выполнение этого практического задания обойдется вам менее чем в несколько центов. Новые пользователи Google Cloud также могут претендовать на бесплатную пробную версию стоимостью 300 долларов США .
- Запишите идентификатор вашего проекта (уникальное имя для всех проектов Google Cloud). Он понадобится вам для настройки и развертывания агента.
Получите ключ API Google AI Studio
Для использования моделей Gemini вам потребуется ключ API от Google AI Studio.
- Перейдите в Google AI Studio .
- Нажмите « Получить ключ API» .
- Создайте новый ключ или используйте существующий. Скопируйте ключ для дальнейшего использования.
4. Создайте структуру проекта агента по написанию статей для блога.
На этом шаге вы настроите каталог и файлы для размещения кода вашего агента для написания блогов на вашем локальном компьютере.
1. Создайте рабочее пространство для агента по написанию статей для блога.
Откройте терминал и выполните следующие команды, чтобы создать отдельный каталог для вашего агента blog-writer и перейти в него:
mkdir bloggeragent
cd bloggeragent
2. Инициализируйте файлы агента.
Фреймворк Google ADK загружает рабочие процессы агента непосредственно из каталога вашего проекта. Создайте необходимые файлы непосредственно в корневом каталоге bloggeragent :
touch requirements.txt .env __init__.py agent.py
5. Установите зависимости и настройте среду.
На этом этапе вы настроите виртуальное окружение Python, установите фреймворк Google ADK и сконфигурируете переменные окружения для аутентификации вашего агента блога с помощью модели Gemini.
1. Настройте требования к агенту.
Откройте файл requirements.txt в каталоге bloggeragent и укажите пакеты, необходимые для агента написания блогов, добавив в него следующее:
google-adk==2.2.0
python-dotenv
2. Создайте виртуальную среду для агента.
В каталоге bloggeragent создайте и активируйте виртуальное окружение Python, чтобы изолировать пакеты агента:
python3 -m venv .venv
source .venv/bin/activate
3. Установите фреймворк ADK.
Установите зависимости, указанные в файле requirements.txt , чтобы оснастить вашу локальную рабочую область Google ADK:
pip install -r requirements.txt
4. Настройка учетных данных API агента.
Откройте созданный вами файл .env в корневой директории проекта и добавьте свой API-ключ Gemini:
GOOGLE_API_KEY=your_api_key
Замените your_api_key на ключ, скопированный вами из Google AI Studio.
6. Создайте многоагентного автора блога.
На этом этапе вы реализуете основной рабочий процесс вашей системы для ведения блога.
Вместо простого чат-бота с одной подсказкой вы создадите сложную многоагентную систему, использующую самокорректирующиеся циклы и проверку структуры для написания высококачественных технических статей. Это соответствует схеме обдумывания/планирования, которую мы обсуждали ранее.
Обзор архитектуры
Вот как взаимодействуют специализированные агенты в вашей системе:
Настройте файл init.py
Откройте __init__.py в текстовом редакторе и добавьте следующий импорт, чтобы предоставить доступ к рабочему процессу агента исполнителю:
from . import agent
Опишите рабочий процесс для агента по написанию статей для блога.
Откройте agent.py в редакторе кода и добавьте следующий код, определяющий Planner, Writer, Validation Checkers и основной агент Blogger:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
Понимание архитектуры агента
Давайте разберем основные компоненты кода, который вы только что добавили в agent.py , чтобы понять, как он реализует процесс планирования и записи данных для нескольких агентов:
1. Субагент BlogPlanner
Агент blog_planner отвечает за планирование контента. Он принимает тему, предоставленную пользователем, и создает структурированный план в формате Markdown (с заголовком, введением, 4-6 разделами и заключением). План сохраняется в общем словаре состояний под ключом "blog_outline" .
2. OutlineValidationChecker
Агент OutlineValidationChecker выступает в роли контролера качества. Он проверяет сгенерированный "blog_outline" в состоянии. Если структура действительна, он отвечает "ok" . В противном случае он возвращает "retry" вместе со списком недостающих элементов.
3. Цикл RobustBlogPlanner
Чтобы предотвратить создание агентом некорректных контуров, мы оборачиваем планировщик и средство проверки валидации в LoopAgent с именем robust_blog_planner . Если проверка не удается и возвращается "retry" , цикл автоматически запускает планировщик снова, до 3 раз, обеспечивая самокоррекцию перед переходом к следующему этапу.
4. Суб-агент BlogWriter
После завершения формирования плана агент blog_writer считывает из состояния переменную "blog_outline" и генерирует полный технический текст статьи в формате Markdown, соответствующий структуре плана и адаптированный для разработчиков программного обеспечения.
5. Цикл проверки и редактирования сообщений в блоге (BlogPostValidationChecker & RobustBlogWriter Loop)
Как и план статьи, окончательный вариант проверяется инструментом BlogPostValidationChecker , чтобы убедиться в наличии и ясности всех ключевых разделов. Автор и проверяющий инструмент объединены в цикл robust_blog_writer , что позволяет инструменту самостоятельно исправлять ошибки до 3 раз, если он их обнаружит.
6. Предоставление доступа к циклам в качестве инструментов.
Мы оборачиваем цикл планировщика ( robust_blog_planner ) и цикл автора ( robust_blog_writer ) в инструменты ( planner_tool и writer_tool ) с помощью AgentTool . Это позволяет другим агентам вызывать эти сложные рабочие процессы, как если бы они были простыми инструментами.
7. Корневой агент Blogger
root_agent (с именем Blogger ) управляет всем рабочим процессом. Получив тему, он получает инструкции, указывающие ему путь:
- Вызовите инструмент
planner_toolдля генерации проверенной структуры. - Вызовите
writer_tool, чтобы написать черновик на основе этого плана. - В завершение сгенерируйте 3 альтернативных заголовка и 2 варианта заголовков для твитов.
Эта многоагентная архитектура обеспечивает надежность, выявляя и исправляя ошибки форматирования или структуры LLM до отображения результата пользователю!
7. Запустите и протестируйте агента.
Теперь пришло время увидеть вашего агента в действии!
1. Запустите веб-интерфейс ADK.
Убедитесь, что в терминале вы находитесь в корневом каталоге проекта bloggeragent и что ваша виртуальная среда активна ( source .venv/bin/activate ), затем запустите веб-интерфейс:
adk web
2. Взаимодействуйте с агентом.
- Откройте браузер и перейдите по адресу
http://127.0.0.1:8000(или по указанному вами порту). - Вы должны увидеть веб-интерфейс ADK с загруженным агентом
Bloggerи его визуальным оформлением (показывающим корневой агент Blogger, указывающий на инструменты RobustBlogPlanner и RobustBlogWriter):
- Введите техническую тему в поле сообщения и нажмите Enter. Вот несколько интересных тестовых вопросов, которые вы можете использовать для оценки работы вашего агента:
-
How to build an AI agent using planning loops -
Explain the difference between REST and gRPC in microservices -
A guide to using Python's asyncio for backend concurrency -
Why developers should use Docker for local database setups
-
- Просмотрите трассировку выполнения в пользовательском интерфейсе. Вы увидите, как
BlogPlannerсоздает план,OutlineValidationCheckerпроверяет его, аBlogWriterпишет окончательный вариант на основе плана:
8. Развертывание в облаке.
Теперь, когда вы убедились, что агент работает локально, давайте развернем его в Google Cloud Run, чтобы другие могли им пользоваться!
Google Cloud Run — это управляемая вычислительная платформа, позволяющая запускать контейнеры без сохранения состояния, которые можно вызывать с помощью веб-запросов или событий Pub/Sub.
1. Предварительные условия для развертывания
Для развертывания агента для написания статей в Cloud Run вам потребуется установить и авторизовать Google Cloud CLI ( gcloud ) на вашем локальном компьютере:
- Установите Google Cloud CLI : если он у вас не установлен, следуйте руководству по установке Google Cloud CLI для вашей операционной системы (macOS, Windows или Linux).
- Аутентификация локального терминала : После установки выполните следующую команду в терминале, чтобы войти в свою учетную запись Google Cloud:
gcloud auth login - Проверка аутентификации : Убедитесь, что ваша учетная запись успешно авторизована и вы можете получить доступ к ресурсам Google Cloud:
gcloud auth list
2. Настройка проекта Google Cloud
Установите активный проект в терминале:
gcloud config set project <YOUR_PROJECT_ID>
Включите необходимые сервисы Google Cloud, которые требуются для создания и развертывания контейнеризированного агента:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Поскольку команда развертывания ADK использует Google Cloud Build для автоматизации процесса сборки, необходимо предоставить учетной записи службы вычислений по умолчанию разрешение на использование Cloud Build.
Номер вашего проекта можно узнать, выполнив следующую команду:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
Выполните следующие команды для привязки необходимых ролей IAM (замените
- Предоставьте Cloud Build разрешение на сборку вашего контейнера:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Предоставьте Gemini Enterprise права доступа, чтобы развернутый агент мог вызывать модели Gemini без необходимости ввода ключа API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. Настройка локальных переменных среды.
Чтобы упростить команду развертывания и избежать опечаток, установите идентификатор вашего проекта в качестве переменной среды в терминале:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. Развертывание с помощью ADK CLI
ADK CLI предоставляет упрощенную команду для развертывания вашего агента в Cloud Run.
Убедитесь, что ваша виртуальная среда активна и вы находитесь в каталоге проекта bloggeragent , затем выполните команду развертывания:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
В процессе развертывания в вашем терминале появятся следующие два вопроса:
- Подтвердите создание репозитория :
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yи нажмите Enter . - Разрешить неавторизованный доступ :
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yи нажмите Enter (это позволит вам получить доступ к веб-интерфейсу ADK в открытом доступе в вашем браузере).
5. Получите доступ к развернутому агенту.
После завершения развертывания команда выведет URL-адрес. Откройте этот URL-адрес в браузере, чтобы получить доступ к работающему, общедоступному веб-интерфейсу ADK!
9. Уборка
Чтобы избежать дальнейших списаний средств с вашего аккаунта Google Cloud, удалите ресурсы, созданные в ходе этого практического занятия.
1. Удалите службу Cloud Run.
Удалите развернутую службу bloggeragent :
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Удалите репозиторий реестра артефактов.
Удалите репозиторий Docker, созданный для хранения собранных образов контейнеров:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. Остановите локальный сервер.
Чтобы остановить локальный сервер ADK, нажмите CTRL+C в терминале, где он запущен, и деактивируйте виртуальное окружение:
deactivate
10. Поздравляем!
Поздравляем! Вы создали своего первого ИИ-агента, используя Google ADK и Gemini.
Что вы узнали
- Основные концепции агентов искусственного интеллекта (рассуждение и действие).
- Как использовать Google ADK для создания многоагентной системы.
- Как запустить и протестировать агента с помощью веб-интерфейса.
Следующие шаги
- Попробуйте добавить в свой агент дополнительные инструменты (например, веб-поиск или вызовы API).
- Следите за обновлениями, скоро выйдет видео 2, где мы интегрируем сервер MCP!