Создание мультиагентной креативной студии с помощью стека агентов Google: ADK, A2A, MCP в Cloud Run и Agent Runtime

1. Обзор

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

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

Агенты, которых вы создадите

Агент

Роль

Специалист по стратегии бренда

Ищет в интернете статистику аудитории, анализ конкурентов и текущие тренды.

Копирайтер

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

Дизайнер

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

Критик

Проверка текста и визуальных элементов – возвращает APPROVED или NEEDS_REVISION с конкретными отзывами.

Менеджер проектов

Создает хронологию проекта и разбивку задач, при необходимости синхронизируя их с Notion через MCP.

Креативный директор

Управляет всеми пятью специалистами по очереди. Вы даете ему один запрос, а он координирует остальных.

Пять агентов развертываются как независимые микросервисы Cloud Run. Они общаются по протоколу A2A – открытому стандарту, не зависящему от языка, поэтому любой агент может вызвать любого другого агента независимо от фреймворка. Креативный директор работает на базе Agent Runtime и удаленно подключается к каждому специалисту.

Архитектура

Системная архитектура

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

  • Создавайте агентов LLM с помощью Google ADK – Agent, системных инструкций и встроенных инструментов.
  • Упаковывайте знания агента, которые можно использовать повторно, в модульные файлы с помощью навыков ADK (SkillToolset).
  • Генерируйте реалистичные изображения, связав текстового агента с моделью генерации изображений через FunctionTool.
  • Интегрируйте внешние API без специального связующего кода с помощью Model Context Protocol (MCP).
  • Превратите любого агента в сервис, вызываемый по сети, с помощью протокола Agent to Agent (A2A) через HTTPS.
  • Управляйте распределенными агентами с помощью RemoteA2aAgent и AgentTool.
  • Упаковывайте и развертывайте независимых агентов как микросервисы Cloud Run.
  • Разместите управляющий агент с сохранением состояния в Agent Runtime.
  • Сжатие контекста позволяет не превышать лимиты контекста в длинных рабочих процессах с несколькими агентами.
  • Создайте цикл контроля качества: критик проверяет выходные данные, а затем при необходимости выполняется автоматическая доработка.

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

  • Проект Google Cloud с включенными платежными функциями.
  • Роль IAM Владелец или Редактор.
  • Базовые знания Python

2. Настройка среды

В этой практической работе мы будем использовать Cloud Shell.

Что такое Cloud Shell?

Cloud Shell — это бесплатная среда Linux на базе браузера, в которой предустановлено все необходимое: gcloud, git, Python, Docker и многое другое. Вам не нужно ничего устанавливать на локальном компьютере.

Чтобы открыть Cloud Shell, нажмите на значок терминала на панели инструментов в правом верхнем углу консоли GCP.

Откройте Cloud Shell на панели инструментов GCP Console.

При первом открытии Cloud Shell вам будет предложено подтвердить аккаунт. Нажмите Verify (Подтвердить).

Диалоговое окно подтверждения аккаунта

Затем нажмите Authorize (Авторизовать), чтобы разрешить Cloud Shell выполнять вызовы Google Cloud API.

Диалоговое окно авторизации Cloud Shell

Cloud Shell готов к работе. В терминале появится приветственное сообщение: Терминал Cloud Shell готов..

Как выполнить аутентификацию и настроить проект

Cloud Shell уже аутентифицирован в вашем аккаунте Google. Подтвердите активный аккаунт и найдите идентификатор проекта:

gcloud config list

Идентификатор проекта также можно посмотреть на панели управления GCP Console на левой боковой панели. Скопируйте его – он понадобится в следующей команде:

Найдите идентификатор проекта в консоли GCP и укажите его в Cloud Shell.

Теперь настройте проект:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"        # Cloud Run deployment region
echo "Project: $PROJECT_ID"

Ожидаемый результат:

Project: my-project-123

Включите необходимые API

gcloud services enable \
    aiplatform.googleapis.com \
    apphub.googleapis.com \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    generativelanguage.googleapis.com \
    iam.googleapis.com \
    cloudresourcemanager.googleapis.com \
    storage.googleapis.com \
    secretmanager.googleapis.com

Это займет около двух минут. Когда все будет готово, вы увидите значок Operation finished successfully.

Как настроить Application Default Credentials (ADC)

Агенты будут вызывать Gemini Enterprise Agent Platform с помощью библиотеки Google Auth, для которой требуются Application Default Credentials, не связанные с аутентификацией CLI gcloud.

Выполните следующую команду:

gcloud auth application-default login

Откроется вкладка браузера с запросом на подтверждение. Нажмите Разрешить. Вы увидите:

Credentials saved to file: ~/.config/gcloud/application_default_credentials.json

Клонируйте хранилище starter

В этой практической работе используется начальный репозиторий – каркас проекта со всей инфраструктурой (файлы Dockerfile, pyproject.toml, скрипты развертывания), но без логики агента, которую вам нужно написать самостоятельно.

git clone https://github.com/Saoussen-CH/mas-a2a-gcp.git ~/ai-creative-studio
cd ~/ai-creative-studio/workshop/starter

Каждый файл agent.py содержит плейсхолдеры # TODO, в которых вы будете писать логику агента. Скрипты Dockerfile, pyproject.toml и deploy уже готовы.

Настройте переменные среды

Скопируйте приведенный пример и вставьте идентификатор проекта за один шаг:

cp .env.example .env
sed -i "s|GOOGLE_CLOUD_PROJECT=your-project-id|GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)|" .env

Затем создайте сегмент GCS, в котором Дизайнер будет хранить сгенерированные изображения, и укажите его название в переменной .env:

export PROJECT_ID=$(gcloud config get-value project)
export BUCKET_NAME="${PROJECT_ID}-campaign-images"

gcloud storage buckets create gs://${BUCKET_NAME} \
    --location=us-central1 \
    --project=${PROJECT_ID}

sed -i "s|GCS_IMAGES_BUCKET=your-project-id-campaign-images|GCS_IMAGES_BUCKET=${BUCKET_NAME}|" .env

Затем настройте поддержку подписанных URL изображений. Креативный директор создает кликабельные ссылки HTTPS для каждого изображения в итоговой сводке кампании. Для этого потребуется сервисный аккаунт, который будет подписывать URL. Чтобы настроить его, выполните следующие команды:

export PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")
export SA_EMAIL="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
export AGENT_RUNTIME_SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Allow your user account to sign URLs locally (adk web)
gcloud iam service-accounts add-iam-policy-binding ${SA_EMAIL} \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountTokenCreator"

# Allow Agent Runtime to sign URLs when deployed
gcloud beta services identity create --service=aiplatform.googleapis.com
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
  --member="serviceAccount:${AGENT_RUNTIME_SA}" \
  --role="roles/iam.serviceAccountTokenCreator"

# Save SA email and project number to .env
grep -q "^SIGNING_SERVICE_ACCOUNT" .env \
  && sed -i "s|^SIGNING_SERVICE_ACCOUNT=.*|SIGNING_SERVICE_ACCOUNT=${SA_EMAIL}|" .env \
  || echo "SIGNING_SERVICE_ACCOUNT=${SA_EMAIL}" >> .env

grep -q "^GOOGLE_CLOUD_PROJECT_NUMBER" .env \
  && sed -i "s|^GOOGLE_CLOUD_PROJECT_NUMBER=.*|GOOGLE_CLOUD_PROJECT_NUMBER=${PROJECT_NUMBER}|" .env \
  || echo "GOOGLE_CLOUD_PROJECT_NUMBER=${PROJECT_NUMBER}" >> .env

Откройте файл .env в редакторе, чтобы проверить все настройки.

cloudshell edit .env

Файл .env откроется на вкладке в редакторе Cloud Shell. Если панель редактора не видна, нажмите кнопку Open Editor (Открыть редактор) на панели инструментов.

На панели инструментов Cloud Shell нажмите Open Editor (Открыть редактор).

Редактор Cloud Shell с деревом файлов проекта

Убедитесь, что проект настроен правильно:

grep GOOGLE_CLOUD_PROJECT .env

Установка зависимостей

Мы используем uv – быстрый современный менеджер пакетов Python, который работает с виртуальными средами и устанавливает их в одном инструменте. Он работает примерно в 10–100 раз быстрее, чем pip, и рекомендуется для управления проектами Python.

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

uv sync

Команда uv sync считывает pyproject.toml и создает каталог .venv/ со всеми зависимостями. У каждого специалиста также есть свой собственный pyproject.toml, используемый исключительно сборками Docker. Общая установка, описанная выше, охватывает все, что вам нужно для локального тестирования.

3. Что такое Google ADK

Прежде чем писать код, давайте разберемся, что такое Agent Development Kit (ADK) – фреймворк, который вы будете использовать для создания каждого агента в этой практической работе.

Что такое ADK?

Agent Development Kit (ADK) – это гибкий модульный фреймворк для разработки и развертывания ИИ-агентов. Хотя ADK оптимизирован для Gemini и экосистемы Google, он не зависит от модели и развертывания и совместим с другими фреймворками. ADK разработан, чтобы сделать создание агентов похожим на разработку ПО. Это упрощает создание, развертывание и оркестрацию агентных архитектур, которые могут выполнять как простые задачи, так и сложные рабочие процессы.

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

Компоненты агента ADK

Каждый агент состоит из четырех блоков:

Заблокировать

Роль

Модель

Большая языковая модель, которая анализирует цели, составляет план и генерирует ответы.

Инструменты

Функции, которые получают данные или выполняют действия, вызывая API или сервисы.

Оркестровка

Сохраняет память и состояние между запросами, маршрутизирует вызовы инструментов, передает результаты обратно в модель.

Время выполнения

Запускает систему при вызове – локально через adk web или как развернутый сервис.

Определение агента

Каждый из пяти агентов в этой практической работе определяется одинаково:

from google.adk.agents import Agent
from google.adk.tools.google_search_tool import google_search

root_agent = Agent(
    name="brand_strategist",                              # unique identifier
    model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"), # the LLM powering this agent
    instruction=SYSTEM_INSTRUCTION,                       # the agent's persona, constraints, and output format
    description="Brand strategist for market research, trend analysis, and competitive insights",
    tools=[google_search],                                # functions the LLM can call
)

Поле

Цель

name

Уникальный идентификатор, используемый оркестраторами для маршрутизации вызовов.

model

Модель Gemini, на которой работает агент

instruction

Системный запрос – определяет роль агента, ограничения и формат вывода.

description

Краткое описание. По нему оркестратор определяет, какого специалиста вызвать.

tools

Функции, которые может вызывать LLM (встроенные, например google_search, или пользовательские функции Python).

Как ADK запускает агента

User message
     │
     ▼
  Agent (LLM)  ← reads instruction + conversation history
     │
     ├─► needs more info? → calls a tool → gets result → continues reasoning
     │
     └─► done reasoning → returns final text response

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

4. Создание и тестирование агента Brand Strategist

Начнем с первого агента – стратега бренда. Этот агент предназначен только для поиска информации о целевой аудитории, анализа конкурентов и поиска популярных тем в Google Поиске.

Откройте файл агента-скелета в редакторе Cloud Shell:

cloudshell edit agents/brand_strategist/agent.py

Вы увидите два раздела # TODO, которые нужно заполнить.

TODO 1 - Write the system instruction

Сначала вы напишете системную инструкцию для агента. Системная инструкция – это строка, которая определяет роль агента, ограничения и формат вывода.

SYSTEM_INSTRUCTION = f"""You are a Brand Strategist specializing in market research and trend analysis.

IMPORTANT: Today's date is {datetime.date.today().strftime("%B %d, %Y")}.
When conducting research, focus on current trends from {datetime.date.today().year}.
Use search queries like "[topic] trends {datetime.date.today().year}" for recent insights.

IMPORTANT: Your role is RESEARCH ONLY. You do NOT create campaign content, captions, or designs.
After providing research insights, your work is complete.

Your expertise:
- Identifying target audience insights and behaviors
- Analyzing competitor strategies
- Researching current social media trends
- Understanding platform algorithms and best practices

You have access to:
- google_search: Search the web for competitors, trends, and market insights

When given a campaign brief:
1. Use google_search to research the target audience's current interests
2. Search for and analyze 2-3 competitor brands
3. Identify 3-5 trending topics related to the product category
4. Provide high-level strategic insights - NOT specific campaign content

DO NOT create captions, copy, designs, or any campaign content.

Format your output as:
**Audience Insights:**
[Key behaviors and preferences based on research]

**Competitive Analysis:**
[What 2-3 competitors are doing - strengths and weaknesses]

**Trending Topics:**
[3-5 relevant trends to consider]

**Key Strategic Insights:**
[High-level themes and positioning opportunities]
"""

TODO 2 - Create the root_agent

Замените неполный фрагмент root_agent следующим кодом:

root_agent = Agent(
    name="brand_strategist",
    model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"),
    instruction=SYSTEM_INSTRUCTION,
    description="Brand strategist for market research, trend analysis, and competitive insights",
    tools=[google_search],
)

Как протестировать локально с помощью веб-интерфейса ADK

Теперь давайте протестируем агента с помощью веб-интерфейса ADK – встроенного интерфейса чата для тестирования агентов перед развертыванием в облаке.

uv run adk web agents --allow_origins='*'

Вы увидите:

INFO: Started server process
INFO: Uvicorn running on http://localhost:8000

Сервер запущен в Cloud Shell:

Чтобы открыть его в браузере, используйте веб-просмотр:

  1. Посмотрите на панель инструментов Cloud Shell в верхней части страницы.
  2. Нажмите на значок Web Preview (Предварительный просмотр) (выглядит как поле со стрелкой вверх в правом верхнем углу панели инструментов Cloud Shell).
  3. Нажмите Change port (Изменить порт), введите 8000 и нажмите Change and Preview (Изменить и посмотреть).

В новой вкладке браузера откроется веб-интерфейс ADK. Нажмите на раскрывающийся список Select an agent (Выбрать агента) в левом верхнем углу. Вы увидите список всех своих агентов.

Выберите brand_strategist, чтобы начать тестирование:

Попробуйте эти тестовые запросы

В окне чата веб-интерфейса ADK попробуйте сделать следующее:

  • Research the eco-friendly water bottle market for health-conscious millennials
  • What are the top Instagram trends in the wellness space in for this year?

Вы должны увидеть, как агент вызывает Google Поиск и возвращает структурированное исследование с разделами Audience Insights (Статистика аудитории), Competitive Analysis (Анализ конкурентов) и Trending Topics (Популярные темы).

5. Создание копирайтера – навыки ADK

Роль. Преврати результаты исследования бренда в подписи для Instagram. Копирайтер создает три варианта подписи в разных тонах (вдохновляющий, образовательный, общественный), каждый с хештегами и призывом к действию.

Концепция: навыки ADK

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

Навыки ADK (SkillToolset, представлены в ADK 1.25.0) позволяют упаковать эти знания в модульные файлы с тремя уровнями загрузки:

  • L1 – frontmatter (name + description в SKILL.md): всегда доступно, используется для поиска навыков.
  • L2 – инструкции (тело SKILL.md): загружаются, когда агент активирует навык.
  • L3 – ресурсы (файлы references/ и assets/): загружаются, только когда агент явно считывает их.

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

Навыки копирайтера в agents/copywriter/skills/instagram-copywriting/:

skills/
  instagram-copywriting/
    SKILL.md                       ← L1 frontmatter (discovery) + L2 instructions (loaded on trigger)
    references/
      platform-guide.md            ← L3: character limits, hashtag tiers, algorithm signals
      caption-formulas.md          ← L3: hook formulas, CTA patterns, full caption structures
    assets/
      brand-voice-examples.md      ← L3: annotated real-world caption examples

Откройте файл непосредственно в редакторе Cloud Shell:

cloudshell edit agents/copywriter/agent.py

TODO 1 – импортируйте load_skill_from_dir и skill_toolset

Найдите комментарий # TODO 1: Import load_skill_from_dir and skill_toolset и добавьте две строки импорта:

from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset

TODO 2 - Load the skill and create a SkillToolset

Найдите два комментария под импортом:

# TODO 2: Load the instagram-copywriting skill from the skills/ directory
# TODO 2: Create a SkillToolset with the loaded skill

Замените их на следующие:

_instagram_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "instagram-copywriting"
)
_copywriting_skills = skill_toolset.SkillToolset(skills=[_instagram_skill])

load_skill_from_dir считывает SKILL.md и любые файлы в references/ и assets/. SkillToolset преобразует его в формат, который принимают агенты ADK, – набор инструментов, а не необработанный навык.

TODO 3 - Register the toolset with the agent

Найдите tools=[], # TODO 3: Add the SkillToolset here и замените на:

tools=[_copywriting_skills],

Откройте файл навыка, чтобы посмотреть его структуру.

cloudshell edit agents/copywriter/skills/instagram-copywriting/SKILL.md

Не закрывайте веб-интерфейс ADK. Используйте раскрывающийся список агентов, чтобы переключиться на copywriter без перезапуска сервера.

Если он не запущен, запустите его снова:

uv run adk web agents --allow_origins='*'

Попробуйте. Выберите в раскрывающемся списке copywriter и отправьте запрос:

You are writing captions for EcoFlow Smart Water Bottle targeting health-conscious millennials aged 25-35.
Audience insight: they prioritize sustainability, track health metrics, and share lifestyle content.
Competitor insight: Hydro Flask dominates with lifestyle branding; S'well leads on premium aesthetics.
Write 3 Instagram captions - one inspirational, one educational, one community-focused. Include 5 hashtags each and a CTA.

6. Создание дизайнера – мультимодальная генерация изображений

Не закрывайте веб-интерфейс ADK. Чтобы переключиться на другого агента, не перезапуская сервер, используйте раскрывающийся список агентов.

Роль. Создай визуальные концепции для каждой подписи и сгенерируй изображения, используя встроенный генератор изображений Gemini. Дизайнер выводит ровно одну визуальную концепцию для каждой подписи с подробным запросом, стилем, цветовой палитрой, настроением и форматом Instagram, а затем сразу же вызывает инструмент generate_image, чтобы создать фактическое изображение и загрузить его в GCS.

Концепция: подключение текстового агента к модели генерации изображений с помощью инструмента

Дизайнер работает на основе gemini-3-flash-preview (текстовой модели, заданной через GEMINI_MODEL в .env), но для генерации изображений требуется специальная модель (gemini-3.1-flash-image). Эта модель не поддерживает вызов функций, поэтому ее нельзя использовать напрямую в качестве агента ADK. Вместо этого он упакован в простую функцию Python и зарегистрирован как FunctionTool.

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

Designer agent (text model)
        │
        │  decides visual concept, writes image prompt
        ▼
  generate_image tool
        │
        │  calls gemini-3.1-flash-image
        │  uploads result to GCS
        ▼
  {"status": "success", "gcs_uri": "gs://..."}
        │
        │  returned to agent, included in response
        ▼
  Critic (receives gcs_uri, passes to Vertex AI for multimodal review)

Откройте файл непосредственно в редакторе Cloud Shell:

cloudshell edit agents/designer/image_gen_tool.py

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

TODO 1 - Call the Gemini image model

Найдите комментарий # TODO 1 и замените его следующим кодом:

        client = genai.Client(vertexai=True, project=project_id, location=location)

        response = client.models.generate_content(
            model=image_model,
            contents=prompt_with_aspect,
            config=types.GenerateContentConfig(
                response_modalities=["IMAGE", "TEXT"],
                http_options=types.HttpOptions(
                    retry_options=types.HttpRetryOptions(
                        attempts=5, exp_base=2, initial_delay=30,
                        http_status_codes=[429, 500, 503, 504],
                    ),
                    timeout=180_000,
                ),
            ),
        )

TODO 2 - Extract image bytes from the response

Найдите комментарий # TODO 2 и замените его следующим кодом:

        image_bytes = None
        mime_type = "image/png"
        for part in response.candidates[0].content.parts:
            if part.inline_data is not None:
                image_bytes = part.inline_data.data
                mime_type = part.inline_data.mime_type or "image/png"
                break

        if not image_bytes:
            return {"status": "error", "error": "Gemini returned no image data"}

TODO 3 - Upload to GCS and return the URI

Найдите комментарий # TODO 3 и замените его следующим кодом:

        ext = "jpg" if "jpeg" in mime_type else "png"
        from google.cloud import storage
        gcs_client = storage.Client(project=project_id)
        bucket = gcs_client.bucket(bucket_name)
        blob_name = f"campaign-images/{concept_name}-{uuid.uuid4().hex[:8]}.{ext}"
        blob = bucket.blob(blob_name)
        blob.upload_from_file(io.BytesIO(image_bytes), content_type=mime_type)
        gcs_uri = f"gs://{bucket_name}/{blob_name}"

Попробуйте. Выберите в раскрывающемся списке designer и отправьте запрос:

Create a visual concept and generate the image for an EcoFlow Smart Water Bottle Instagram post targeting health-conscious millennials.
Style: clean, modern, lifestyle-focused. Include a detailed prompt with color palette, mood, and format (1080x1080 or 1080x1350).

7. Создание критика – структурированные выходные данные

Роль: проверка качества текстов и визуальных материалов перед их передачей менеджеру проекта. Критик оценивает оба результата и возвращает APPROVED или NEEDS_REVISION с конкретными предложениями. Если во входных данных есть значения gcs_uri, инструмент review_image визуально проверяет каждое сгенерированное изображение перед оценкой.

Концепция: когда использовать модель Pydantic для вывода Gemini

Правило касается того, кто использует результат:

  • Код Python использует его → используйте response_schema + Pydantic. Код не может обрабатывать неоднозначность, поэтому вам нужна гарантированная структура для надежного извлечения полей.
  • Для LLM достаточно текстового формата и системных инструкций. Большие языковые модели понимают правила форматирования и допускают вариативность.

В review_image коду Python требуются score, approval_status, what_works, issues и suggestions в качестве типизированных значений. Передача response_schema=_GeminiReview ограничивает Gemini на уровне API, чтобы возвращать действительный JSON; model_validate_json() анализирует его в типизированный объект, который ваш код может надежно использовать.

class _GeminiReview(BaseModel):
    score: int = Field(ge=1, le=10)
    approval_status: Literal["APPROVED", "NEEDS_REVISION"]
    what_works: str
    issues: str
    suggestions: str

Откройте файл непосредственно в редакторе Cloud Shell:

cloudshell edit agents/critic/image_review_tool.py

Модели Pydantic и запрос предоставлены. Выполните три задачи в следующем порядке:

TODO 1 - Create an image part from the GCS URI

Найдите комментарий # TODO 1 и замените его следующим кодом:

        image_part = types.Part.from_uri(file_uri=gcs_uri, mime_type=mime_type)

TODO 2 - Call Gemini with a structured response schema

Найдите комментарий # TODO 2 и замените его следующим кодом:

        response = client.models.generate_content(
            model=model,
            contents=[image_part, prompt],
            config=types.GenerateContentConfig(
                response_schema=_GeminiReview,
                response_mime_type="application/json",
            ),
        )

TODO 3 - Parse the response and return the result

Найдите комментарий # TODO 3 и замените его следующим кодом:

        review = _GeminiReview.model_validate_json(response.text)
        return ImageReviewResult(status="success", concept_name=concept_name, **review.model_dump())

Попробуйте. Выберите в раскрывающемся списке critic и отправьте запрос:

Review this Instagram caption for an eco-friendly water bottle brand targeting millennials:
"Hydrate smarter, live greener. 💧 Our EcoFlow bottle tracks your intake, keeps your drink cold for 24h, and never touches single-use plastic. Because what you drink from matters as much as what you drink. #EcoFlow #HydrationGoals #SustainableLiving #ZeroWaste #HealthyHabits - Shop link in bio."
Score it and indicate APPROVED or NEEDS_REVISION with specific feedback.

Убедитесь, что ответ содержит **POSTS REVIEW:**, Status: APPROVED (или NEEDS_REVISION) и **OVERALL ASSESSMENT:**. Если эти разделы есть, критика можно подключать к оркестратору.

После тестирования всех трех агентов нажмите Ctrl+C, чтобы остановить сервер.

8. Создание агента для управления проектами с помощью MCP

Менеджер проектов представляет новую концепцию – MCP (Model Context Protocol).

Откройте файл.

cloudshell edit agents/project_manager/agent.py

Этот файл сложнее – в нем есть функция create_project_manager_agent() с двумя ветвями: одна без Notion (хронологии только с текстом), а другая с набором инструментов Notion MCP. Вам нужно будет заполнить оба поля.

Какие проблемы решает MCP

Вашему агенту нужно вызвать внешний сервис, например создать страницу в Notion. Вы можете написать код Python, который напрямую вызывает Notion REST API. Но затем:

  • Каждый разработчик пишет свою оболочку
  • Вам нужно поддерживать код интеграции.
  • LLM не знает о существовании API, пока вы не опишете каждую конечную точку вручную.

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

Что такое MCP?

MCP (Model Context Protocol) – это открытый стандарт (опубликованный Anthropic) для подключения ИИ-агентов к внешним инструментам и источникам данных. Это своего рода универсальный адаптер.

MCP-сервер – это небольшая программа, которая:

  1. Оболочка для внешнего API (Notion, GitHub, базы данных, файловые системы и т. д.)
  2. Предоставляет этот API в виде списка типизированных и задокументированных инструментов.
  3. Взаимодействует с агентом по простому протоколу (stdio или HTTP).

Агент подключается к MCP-серверу, автоматически обнаруживает доступные инструменты и может вызывать их, как и любые другие инструменты. LLM видит API-post-page(...) как вызываемую функцию.

A2A vs MCP - what's the difference?

Это распространенная причина путаницы. Вот ключевое различие:

A2A

MCP

Что подключается

Агент ↔ Агент

Агент ↔ внешний инструмент/сервис

Другая сторона –

Другой агент LLM

Оболочка API (без LLM)

Пример

Креативный директор звонит бренд-стратегу

Менеджер проектов вызывает Notion API

Протокол

JSON-RPC через HTTPS

Поток stdio или HTTP

Определяется

Google

Anthropic

Взгляните на это следующим образом:

  • A2A – как агенты общаются друг с другом.
  • MCP – как агенты взаимодействуют с инструментами и сервисами.

В этом проекте используются оба:

Creative Director
    │
    │  (A2A)  Brand Strategist ─── (google_search tool built into ADK)
    │  (A2A)  Copywriter
    │  (A2A)  Designer
    │  (A2A)  Critic
    │  (A2A)  Project Manager
                   │
                   │  (MCP)  notion-mcp-server ──► Notion REST API

Как работает MCP в этом проекте

Когда агент запускается, ADK запускает notion-mcp-server как дочерний процесс. В этом процессе инструменты предоставляются непосредственно LLM:

Инструмент

Описание

API-retrieve-a-database

Получает схему (названия свойств, типы, допустимые значения)

API-post-database-query

Запрашивает существующие страницы.

API-post-page

Создать страницу

API-patch-page

Обновляет существующую страницу.

LLM вызывает их как любую другую функцию, не зная, что они проходят через MCP к REST API Notion.

Почему stdio? Почему не просто HTTP?

MCP-сервер работает как дочерний процесс агента, обмениваясь данными через stdin/stdout. Вот что это значит:

  • Дополнительный сетевой порт не требуется
  • Жизненным циклом управляет агент (запускается по запросу, останавливается при выходе)
  • Все поставляется в одном образе Docker – не нужно развертывать отдельный сервис.

Включите интеграцию с Notion (необязательно)

Вы можете пропустить этот раздел. Агент Project Manager всегда создает полный текстовый график кампании, независимо от того, используется ли Notion. Если вы пропустите этот шаг, агент перейдет в режим работы с оперативной памятью и выведет хронологию в чат в виде обычного текста. Ничего не сломается, просто задачи не будут появляться в базе данных Notion. Если вы хотите пропустить этот шаг, перейдите к TODO 1.

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

Шаг 1. Создайте базу данных Notion на основе шаблона

В качестве базы данных мы используем официальный шаблон Notion Projects & Tasks. Мы намеренно выбрали этот шаблон, чтобы продемонстрировать сложную реальную ситуацию: в нем есть несколько типов свойств (статус, диапазоны дат, отношения, выбор) с неочевидными названиями. Это отличный тест динамического обнаружения схем MCP: агент должен определить точные названия свойств во время выполнения, а не использовать жестко закодированные.

Нажмите на ссылку ниже, чтобы добавить шаблон в рабочую область Notion:

→ Добавьте шаблон Projects & Tasks (Проекты и задачи) в Notion

Шаблон Notion Projects & Tasks в Marketplace

После этого у вас будет две связанные базы данных: Проекты и Задачи. В шаблоне есть примеры записей. Удалите их все, прежде чем продолжить, чтобы у агента было чистое рабочее пространство (выберите все → Удалить).

Шаг 2. Создайте интеграцию с Notion

Создайте интеграцию:

  1. Перейдите на страницу notion.so/my-integrations.
  2. Нажмите New Integration (Новая интеграция) и укажите название AI Creative Studio.
  3. Свяжите его со своей рабочей областью
  4. Нажмите Configure settings (Задать настройки) и убедитесь, что выбраны функции Read content (Чтение контента), Update content (Обновление контента) и Insert content (Вставка контента).

Настройки интеграции Notion – назовите ее "Творческая ИИ-студия" и скопируйте токен

  1. Скопируйте токен внутренней интеграции (ntn_...) и вставьте его в файл .env:
NOTION_TOKEN=ntn_your-token-here

Подключите интеграцию к базам данных:

  1. Откройте страницу шаблона, который вы только что скопировали, и нажмите на базу данных Projects (Проекты).
  2. Нажмите на значок меню ... в правом верхнем углу и выберите Connections (Подключения) > Add a connection (Добавить подключение) > AI Creative Studio.

Чтобы поделиться данными с интеграцией, нажмите "Подключения" в меню базы данных.

Творческая ИИ-студия появится в списке активных подключений.

  1. Повторите эти действия для базы данных Задачи.

Получите идентификаторы баз данных:

  1. Нажмите на ссылку базы данных Projects, чтобы открыть ее. Она откроется на отдельной странице с URL, похожим на следующий:
https://www.notion.so/9887b6a94f7f83f68f8581e038d1aaa4?v=2c37b6a94f7f838685f1086e312c7278

Открытие базы данных проектов со страницы шаблона

Идентификатор базы данных – это первый UUID в URL, то есть все, что находится до ?v=:

https://www.notion.so/{DATABASE_ID}?v=...
                       ^^^^^^^^^^^^^^^^
                       9887b6a94f7f83f68f8581e038d1aaa4  ← this is your DATABASE_ID
  1. Повторите эти действия для ссылки на базу данных Tasks, чтобы получить ее идентификатор.
  2. Добавьте все три значения в .env:
NOTION_TOKEN=ntn_your-token-here
NOTION_PROJECT_DATABASE_ID=9887b6a94f7f83f68f8581e038d1aaa4   # <-- your Projects DB ID
NOTION_TASKS_DATABASE_ID=your-tasks-db-id                      # <-- your Tasks DB ID

Шаг 3. Установите MCP-сервер Notion

Менеджер проектов подключается к Notion через официальный пакет @notionhq/notion-mcp-server Node.js. Установите его глобально:

npm install -g @notionhq/notion-mcp-server@1.9.1

Проверьте установку:

npm list -g @notionhq/notion-mcp-server

Ожидаемый результат:

└── @notionhq/notion-mcp-server@1.9.1

notion-mcp-server: command not found

? Убедитесь, что Node.js установлен (node --version) и что глобальный bin npm находится в PATH (export PATH=$PATH:$(npm bin -g)).

Шаг 4. Проверьте файл .env

Откройте .env и убедитесь, что все три значения Notion заданы (вы добавили их на шаге 2):

cloudshell edit .env
NOTION_TOKEN=ntn_...                           # integration token
NOTION_PROJECT_DATABASE_ID=...                 # Projects database ID
NOTION_TASKS_DATABASE_ID=...                   # Tasks database ID

Агент Project Manager автоматически обнаруживает эти переменные при запуске и включает набор инструментов Notion MCP.

Как работает обнаружение схем

Менеджер проектов использует динамическое обнаружение схемы – он никогда не задает в коде названия свойств Notion:

Step 1: Call API-retrieve-a-database to discover exact property names
Step 2: Read the "properties" object in the response
Step 3: Use ONLY discovered property names (case-sensitive) in API calls
Step 4: For select/status fields, use only values from the options array

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

TODO 1 - Write the system instruction

Стартовый код уже вычисляет notion_section – пустую строку, если Notion не настроен, или блок, содержащий идентификаторы баз данных и полные инструкции по работе с инструментами, если он настроен. Это позволяет полностью исключить инструкции Notion из запроса агента, не использующего Notion. LLM никогда не видит правила для инструментов, которых у него нет.

Ваша задача – заменить плейсхолдер return реальной системной инструкцией, в которой используется {notion_section}.

    return f"""You are a Project Manager specializing in creative campaign execution.

Today's date is {datetime.date.today().strftime("%B %d, %Y")}.
Use this as the starting point for all timelines.

Your goal: create a complete project plan for the campaign.
{notion_section}
**Project Timeline:**
Phase 1: Strategy & Research | [date] → [date] | [key activities]
Phase 2: Content Creation    | [date] → [date] | [key activities]
Phase 3: Review & Revision   | [date] → [date] | [key activities]
Phase 4: Launch & Monitoring | [date] → [date] | [key activities]

**Task List:**
| Task | Owner | Deadline | Status |
[list each task with realistic deadlines from today; set Owner to TBD]

**Budget Breakdown:**
[by category with approximate allocations]

**Milestones:**
[3-5 key checkpoints with dates]

**Notion Status:**
[What happened - e.g. "Project created (ID: xxx), 8 tasks linked" or "Notion not configured - text timeline only"]
"""

TODO 2 - Agent without Notion

Внутри create_project_manager_agent() в ветке if not notion_token замените неполного агента следующим:

        return Agent(
            name="project_manager",
            model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"),
            generate_content_config=GENERATE_CONTENT_CONFIG,
            instruction=get_system_instruction(),
            description="Project manager that creates campaign timelines and task breakdowns",
        )

TODO 3 - Agent with Notion MCP

Примечание. В исходном файле уже есть обратный вызов handle_notion_error, расположенный над create_project_manager_agent(). Он перехватывает ошибки Notion API (400/404) и заменяет необработанные полезные нагрузки ошибок понятными сообщениями, чтобы LLM могла самостоятельно исправить ситуацию. Вам нужно просто подключить его через after_tool_callback.

Сначала прочитайте оба идентификатора базы данных в верхней части create_project_manager_agent():

    notion_token           = os.getenv("NOTION_TOKEN")
    notion_project_db_id   = os.getenv("NOTION_PROJECT_DATABASE_ID")
    notion_tasks_db_id     = os.getenv("NOTION_TASKS_DATABASE_ID")

Затем в ветке else создайте набор инструментов MCP и агент:

        from google.adk.tools.mcp_tool import McpToolset, StdioConnectionParams
        from mcp import StdioServerParameters

        server_params = StdioServerParameters(
            command="notion-mcp-server",
            env={
                "NOTION_TOKEN": notion_token,
                "PATH": os.environ.get("PATH", ""),
            }
        )
        notion_toolset = McpToolset(
            connection_params=StdioConnectionParams(
                server_params=server_params,
                timeout=30.0
            )
        )

        return Agent(
            name="project_manager",
            model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"),
            generate_content_config=GENERATE_CONTENT_CONFIG,
            after_tool_callback=handle_notion_error,
            instruction=get_system_instruction(
                project_database_id=notion_project_db_id,
                tasks_database_id=notion_tasks_db_id,
            ),
            description="Project manager with Notion integration for task tracking",
            tools=[notion_toolset],
        )

Рекомендация. Не допускайте критических ошибок при необязательных интеграциях. Текстовая хронология всегда является основным результатом; Notion является дополнительным.

Протестируйте менеджер проектов локально с помощью ADK Web

uv run adk web agents --allow_origins='*'

Откройте Web Preview на порте 8000. В раскрывающемся списке агентов выберите project_manager и попробуйте сделать следующее:

Create a project plan for a GreenBrew organic coffee brand Instagram campaign.
Budget: $2,500. Launch in 3 weeks. Target audience: eco-conscious millennials aged 22-30.
Include phases, tasks with deadlines from today, and milestones.

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

9. Что такое протокол A2A

Для подключения агентов в системе мы будем использовать протокол Agent-to-Agent (A2A). Давайте разберемся, как это работает.

Проблема, которую решает A2A

Представьте, что у вас есть агент-стратег, созданный с помощью ADK, и агент-копирайтер, созданный с помощью LangGraph. Как они вызывают друг друга? Они говорят на разных внутренних языках. Вам придется каждый раз писать собственный связующий код.

A2A решает эту проблему, определяя универсальный язык, на котором может говорить любой агент, независимо от фреймворка. Это как HTTP в мире агентов – стандарт, который все принимают, чтобы каждый мог общаться с каждым.

Что такое A2A?

Agent-to-Agent (A2A) – это открытый стандарт для взаимодействия агентов, опубликованный Google. Она определяет:

  1. Как агент описывает себя – карточка агента на странице /.well-known/agent.json
  2. Как это называет другой агент: JSON-RPC по HTTPS.
  3. Как возвращаются результаты – в виде потока или одного ответа.

Что делает A2A гибким:

  • Независимость от языка: агенты Python могут общаться с агентами TypeScript.
  • Независимость от фреймворка – агенты ADK могут взаимодействовать с агентами LangGraph или CrewAI.
  • Независимость от инфраструктуры – локальные агенты могут взаимодействовать с облачными.

Как это работает – пошаговое руководство

Creative Director                  Brand Strategist
      │                                  │
      │  1. GET /.well-known/agent.json  │
      │ ────────────────────────────────►│
      │  ◄──── agent card (name, url,    │
      │         skills, capabilities) ───│
      │                                  │
      │  2. POST /                       │
      │     {"method": "tasks/send",     │
      │      "params": {"message": ...}} │
      │ ────────────────────────────────►│
      │                                  │  LLM does
      │                                  │  the work...
      │  3. streaming response chunks    │
      │  ◄───────────────────────────────│
      │  ◄───────────────────────────────│
      │  ◄───────────────────────────────│

Шаг 1. Обнаружение. Оркестратор один раз запрашивает карточку агента, чтобы узнать его название, URL и возможности.

Шаг 2. Вызов. Оркестратор отправляет задачу через JSON-RPC POST. Тело содержит сообщение (запрос для специалиста).

Шаг 3. Ответ. Специалист возвращает ответ частями, как при обычном вызове LLM.

Карточка агента

Каждый агент публикует описание по адресу /.well-known/agent.json. Это как визитная карточка – она рассказывает миру, что может делать агент и как с ним связаться:

{
  "name": "brand_strategist",
  "description": "Market research and competitive analysis",
  "url": "https://brand-strategist-xyz.run.app",
  "capabilities": { "streaming": true },
  "skills": [
    {
      "id": "market_research",
      "description": "Research target audiences, competitors, and trends"
    }
  ]
}

Оркестратор считывает эту карточку, чтобы создать объект RemoteA2aAgent. При этом ему не нужно знать, как устроен специалист.

Как предоставить доступ к агенту через A2A в ADK

to_a2a() упаковывает любого агента ADK в приложение FastAPI, совместимое с A2A. Одна строка:

from google.adk.a2a.utils.agent_to_a2a import to_a2a

# root_agent = your normal ADK Agent(...)
a2a_app = to_a2a(root_agent, host=PUBLIC_HOST, port=PUBLIC_PORT, protocol=PROTOCOL)
uvicorn.run(a2a_app, host=HOST, port=PORT)

При этом автоматически создаются:

  • /.well-known/agent.json – карточка агента;
  • / – конечная точка JSON-RPC (все запросы задач A2A направляются по корневому пути).

10. Как сделать агентов доступными в качестве сервисов A2A

Чтобы сделать агентов доступными в качестве сервисов A2A, можно использовать служебную функцию to_a2a() из ADK.

Как работает to_a2a()

from google.adk.a2a.utils.agent_to_a2a import to_a2a

a2a_app = to_a2a(root_agent, host=PUBLIC_HOST, port=PUBLIC_PORT, protocol=PROTOCOL)
uvicorn.run(a2a_app, host=HOST, port=PORT)

to_a2a() упаковывает агент ADK в приложение FastAPI, которое автоматически предоставляет:

  • /.well-known/agent.json – карточка агента (название, описание, возможности);
  • /a2a/{agent_name} – конечная точка JSON-RPC для получения задач.

В коде каждого агента уже есть блок __main__, который упаковывает агента в сервер A2A с помощью to_a2a(). Вам не нужно писать этот код – он предоставляется.

Как работает конфигурация с двумя URL

При запуске python agent.py блок __main__ использует две отдельные конфигурации URL:

# Where the server actually listens (network interface):
HOST = "0.0.0.0"
PORT = 8082  # Brand Strategist (others use 8083–8086 locally)

# What gets advertised in the agent card (the address other agents use to reach it):
PUBLIC_HOST = os.getenv("PUBLIC_HOST", "localhost")
PUBLIC_PORT = int(os.getenv("PUBLIC_PORT", str(PORT)))
PROTOCOL    = os.getenv("PROTOCOL", "http")

a2a_app = to_a2a(root_agent, host=PUBLIC_HOST, port=PUBLIC_PORT, protocol=PROTOCOL)
uvicorn.run(a2a_app, host=HOST, port=PORT)

Среда

HOST:PORT (прослушивания)

PUBLIC_HOST:PUBLIC_PORT (рекламируется в карточке агента)

Локальные

0.0.0.0:8082

http://localhost:8082

Cloud Run

0.0.0.0:8080

https://brand-strategist-xyz.run.app:443

Локально оба указывают на один и тот же компьютер. В Cloud Run контейнер прослушивает внутренний порт 8080, но карточка агента должна объявлять общедоступный URL HTTPS, иначе креативный директор не сможет связаться со специалистом извне контейнера.

Запустите все пять специализированных серверов A2A

Давайте запустим все 5 специалистов в качестве серверов A2A одновременно, а затем протестируем креативного директора, локально указывающего на них.

Откройте пять отдельных терминалов Cloud Shell (нажмите на значок + на панели вкладок терминала) и запустите по одному агенту в каждом терминале.

uv run автоматически активирует .venv, поэтому вам не нужно вручную source на каждом терминале.

Терминал 1 – специалист по стратегии бренда (порт 8082):

cd ~/ai-creative-studio/workshop/starter
PORT=8082 uv run agents/brand_strategist/agent.py

Терминал 2 – копирайтер (порт 8083):

cd ~/ai-creative-studio/workshop/starter
PORT=8083 uv run agents/copywriter/agent.py

Терминал 3 – Designer (порт 8084):

cd ~/ai-creative-studio/workshop/starter
PORT=8084 uv run agents/designer/agent.py

Терминал 4 – Critic (порт 8085):

cd ~/ai-creative-studio/workshop/starter
PORT=8085 uv run agents/critic/agent.py

Терминал 5 – менеджер проектов (порт 8086):

cd ~/ai-creative-studio/workshop/starter
PORT=8086 uv run agents/project_manager/agent.py

Укажите URL localhost в файле .env

В Терминале 6 обновите .env, указав URL локальных агентов, чтобы креативный директор мог их найти.

cd ~/ai-creative-studio/workshop/starter

sed -i \
  -e 's|STRATEGIST_AGENT_URL=.*|STRATEGIST_AGENT_URL=http://localhost:8082|' \
  -e 's|COPYWRITER_AGENT_URL=.*|COPYWRITER_AGENT_URL=http://localhost:8083|' \
  -e 's|DESIGNER_AGENT_URL=.*|DESIGNER_AGENT_URL=http://localhost:8084|' \
  -e 's|CRITIC_AGENT_URL=.*|CRITIC_AGENT_URL=http://localhost:8085|' \
  -e 's|PM_AGENT_URL=.*|PM_AGENT_URL=http://localhost:8086|' \
  .env

Как проверить агентов с помощью A2A Inspector

A2A Inspector – это инструмент разработчика с открытым исходным кодом, который поддерживает протокол A2A. Она позволяет напрямую подключаться к любому работающему A2A-агенту, читать его карточку и отправлять задачи, не создавая клиентский код.

Что вы увидите:

  • Карточка агента – структурированные метаданные, которые агент передает: название, описание, поддерживаемые режимы ввода и вывода, а также URL конечной точки. Это то, что читает креативный директор, когда находит специалиста.
  • Интерфейс чата – отправляйте агенту любые сообщения по протоколу A2A и просматривайте необработанные ответы. Вы можете протестировать подсказки по отдельности, прежде чем связывать агентов вместе.
  • Проверка протокола. Инспектор проверяет, соответствует ли карточка агента спецификации A2A, и выявляет отсутствующие поля или неправильные ответы.

Почему это важно. Когда вы позже развернете Cloud Run, Creative Director обнаружит каждого специалиста, получив его карточку агента из /.well-known/agent.json. Если карточка неверна (неправильный URL, отсутствуют возможности), оркестратор не выдает ошибку. Инспектор позволяет выявлять такие проблемы локально, до развертывания в облаке.

Карточка агента &quot;Стратег бренда&quot;

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

Сведения о карточке агента

Как установить и запустить инспектор

cd ~/ai-creative-studio/workshop
./setup_inspector.sh

Команда .env update выполняется один раз. Запустите инспектор в Терминале 6:

cd ~/a2a-inspector
bash scripts/run.sh

Чтобы открыть интерфейс инспектора, выберите Web Preview (Веб-просмотр) > Change port (Изменить порт) и введите 5001.

Связаться со специалистом по стратегии бренда

Введите http://localhost:8082 в поле URL инспектора и нажмите Подключить. Инспектор получает карточку агента и показывает метаданные специалиста.

Инспектор A2A подключен к специалисту по стратегии бренда

Что показывает карточка агента

Карточка агента – это не просто метаданные, а полный контракт возможностей, которые агент рекламирует в сети. Подключитесь к менеджеру проектов (http://localhost:8086), чтобы увидеть самый подробный пример:

{
  "name": "project_manager",
  "description": "Project manager with Notion integration for task tracking",
  "protocolVersion": "0.3.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "project_manager",
      "name": "model",
      "tags": ["llm"],
      "description": "... full system instruction including today's date and Notion database IDs ..."
    },
    {
      "id": "project_manager-API-post-page",
      "name": "API-post-page",
      "tags": ["llm", "tools"],
      "description": "Notion | Create a page"
    },
    {
      "id": "project_manager-API-retrieve-a-database",
      "name": "API-retrieve-a-database",
      "tags": ["llm", "tools"],
      "description": "Notion | Retrieve a database"
    }
  ]
}

Три основных причины:

1. Инструменты MCP становятся навыками A2A. Каждый инструмент Notion, к которому у менеджера проектов есть доступ (API-post-page, API-retrieve-a-database и т. д.), указан в карточке агента как отдельный навык. Любой другой агент в сети может узнать, какие именно инструменты может использовать этот агент, не читая код.

2. Системная инструкция встроена.description первого навыка содержит полную системную инструкцию, включая сегодняшнюю дату и идентификаторы баз данных Notion. Так креативный директор узнает, что нужно передать при вызове менеджера проекта.

3. URL – это конечная точка в реальном времени. Поле url – это именно то, что использует RemoteA2aAgent, когда креативный директор вызывает этого специалиста. Если URL в карточке указан неверно, оркестратор не сможет связаться с агентом.

Поэтому инспектор – это мощный инструмент отладки: одного взгляда на карточку агента достаточно, чтобы понять, работает ли он, какие инструменты у него есть и правильно ли указана конечная точка.

Отправьте тестовое сообщение

После подключения введите запрос на панели чата и отправьте его. Инспектор отправляет его как задачу A2A и передает ответ обратно – так же, как креативный директор будет вызывать этого агента в рабочей среде.

Чат со специалистом по стратегии бренда в A2A Inspector

Чтобы протестировать каждого специалиста по отдельности, укажите в инспекторе любой локальный порт (8082–8086).

11. Создайте оркестратор креативного директора

Креативный директор – это главный дирижер. Он считывает URL специалистов из переменных среды, упаковывает каждый из них как RemoteA2aAgent и предоставляет их как AgentTool, которые может вызывать LLM.

Убедитесь, что пять специализированных агентов все ещё работают (терминалы 1–5 из шага 10).

В Терминале 6 (терминал инспектора A2A) остановите инспектор с помощью Ctrl+C.

Откройте файл.

cd ~/ai-creative-studio/workshop/starter
cloudshell edit agents/creative_director/agent.py

В этом файле три задачи. Выполняйте их по порядку.

TODO 1 - Review the already written system instruction

Системная инструкция находится в файле prompt.py в том же каталоге и импортируется автоматически.

from .prompt import SYSTEM_INSTRUCTION_TEMPLATE

Откройте prompt.py, чтобы прочитать его, прежде чем продолжить.

cloudshell edit agents/creative_director/prompt.py

Важно понимать, как он работает, поскольку он управляет всем процессом оркестрации.

Почему запрос для оркестратора управляет всем

Откройте prompt.py рядом с этим разделом. Примеры ниже относятся к определенным его частям.

Запрос в prompt.py – это не просто документация, а панель управления всей системой. Плохо структурированный запрос к оркестратору приводит к тому, что агенты вызываются не по порядку, контент генерируется оркестратором, а не специалистами, рабочие процессы продолжаются после сбоев, а контекст незаметно теряется между агентами. Эти девять элементов предотвращают наиболее распространенные сбои:

Элемент 0. Сначала планируйте, потом действуйте

Это самый важный элемент. Прежде чем вызвать специалиста, оркестратор должен составить нумерованный план:

I'll create your campaign by coordinating the specialist agents in sequence:
1. Brand Strategist - develop positioning and audience insights
2. Copywriter - write captions using those insights
3. Visual Designer - create image prompts aligned with the copy
4. Critic - review and score the full package
5. Project Manager - build the timeline and task breakdown

Без этого шага LLM сразу переходит к вызовам инструментов и теряет понимание того, на каком этапе рабочего процесса она находится, особенно после получения длинного ответа от специалиста. План помогает организатору ориентироваться в процессе: он знает, на каком шаге находится, что будет дальше и как выглядит завершенный запуск. Если этого не сделать, оркестратор может остановиться в середине рабочего процесса или повторить шаги.

Элемент 1. Явное определение роли

❌ "You are a helpful creative assistant."
✅ "You orchestrate specialists. You do NOT write captions, designs, or timelines yourself."

Без явного запрета LLM иногда пропускает вызов специалистов и генерирует контент напрямую – это быстрее, и она "знает", как это сделать. Инструкция должна сделать это неправильным.

Элемент 2. Синтаксис вызова инструмента с неправильными шаблонами

Просто показать правильный синтаксис недостаточно. LLM может генерировать вызовы, которые выглядят правдоподобно, но не работают. В запросе явно указаны как правильный шаблон, так и те, которые никогда не должны использоваться:

✅ copywriter(request="...")          ← correct
❌ print(copywriter(...))             ← breaks silently
❌ default_api.copywriter(...)        ← breaks silently
❌ copywriter.run(...)                ← breaks silently
❌ agents.copywriter(...)             ← breaks silently

Явное перечисление неправильных шаблонов позволило сократить количество некорректных вызовов инструментов примерно на 95 %.

Элемент 3. Пошаговое описание последовательного выполнения

a) Call the tool
b) Wait for tool_output
c) Verify the output is not an error
d) Confirm to the user: "✓ Brand Strategist complete"
e) Then move to the next agent

Без шагов "б" и "в" LLM может вызвать двух агентов одновременно или предположить, что вызов прошел успешно, и продолжить работу, не дожидаясь ответа.

Элемент 4. Директивы об ошибках: STOP, report, do not proceed

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

Элемент 5. Правила передачи контекста

У удаленных агентов нет истории чата. Когда оркестратор вызывает копирайтера через A2A, копирайтер видит только сообщение в этом единственном запросе – он понятия не имеет, что сказал бренд-стратег. Оркестратор должен явно объединять предыдущие выходные данные в каждый последующий вызов:

copywriter(request="Create 3 posts for EcoFlow water bottle targeting millennials.
Use these insights from the Brand Strategist: [paste full strategist output here].
Create engaging captions with hashtags.")

В инструкции это указано явно: "У удаленных агентов НЕТ общей памяти – вы должны явно передавать предыдущие выходные данные". Без этого каждый агент работает вслепую.

Элемент 6. Классификация запросов: простые и сложные

Не для каждого запроса нужны все пять агентов. Запрос указывает оркестратору классифицировать запрос перед планированием:

SIMPLE  → one agent needed
  "Research the eco-friendly water bottle market" → brand_strategist only
  "Write 3 Instagram captions"                    → copywriter only

COMPLEX → all agents sequentially
  "Create a complete campaign with timeline"      → all 5 agents

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

Элемент 7. Правила коммуникации: показывать полные результаты, без фильтрации

В запросе явно указано, что координатор не должен обобщать или редактировать то, что возвращают специалисты:

- DO NOT summarize unless the output exceeds 2000 words
- DO NOT filter or edit agent responses
- Show the user exactly what each specialist produced
- NEVER say results are ready unless you received them in tool_output

Без этого оркестратор переписывает ответы специалистов своими словами, теряя детали, допуская ошибки и сводя на нет саму цель наличия специалистов.

Элемент 8. Завершение рабочего процесса: никогда не останавливайтесь раньше времени

Неявный, но критический режим сбоя: оркестратор объявляет план из пяти шагов, выполняет три шага, а затем представляет результаты так, как будто все сделано. Чтобы этого не произошло, в запросе есть контрольный список, который должен быть выполнен, прежде чем оркестратор сможет завершить работу:

✓ Did I announce a plan with N agents?
✓ Have I called ALL N agents from my plan?
✓ Did each agent respond successfully?
✓ Am I presenting complete results from ALL agents?

If any answer is NO → continue executing the remaining agents.

Это не позволит оркестратору считать частичный запуск завершенным.

Цикл контроля качества

Процесс проверки – самая сложная часть prompt.py. Откройте раздел ## REVISION WORKFLOW и следуйте инструкциям.

Принцип работы

После ответа Критика Креативный директор не переходит вслепую к Менеджеру проектов. Он считывает выходные данные Критика и разветвляется:

Critic output
      │
      ├── "All Approved: YES"
      │         └──► proceed to Project Manager
      │
      └── "Status: NEEDS_REVISION"
                │
                ├── posts fail   → call copywriter again with feedback
                ├── visuals fail → call designer again with feedback
                └── both fail    → call copywriter, then designer
                          │
                          └──► revised output → Project Manager
                               (1 revision max per deliverable)

Это работает на основе LLM, а не кода

Ранее в этой практической работе упоминалось, что оркестратор анализирует ответ критика. Для этого не используется код Python, регулярные выражения или сопоставление строк. Креативный директор – это большая языковая модель, которая читает собственные инструкции. В инструкции говорится:

Look for "Status: NEEDS_REVISION" in the critic's response.
Posts need revision  → call copywriter
Visuals need revision → call designer

LLM считывает эти строки в выходных данных критика и следует по ветке. Вот почему формат Критика не подлежит обсуждению: если Критик напишет "нужно доработать" вместо NEEDS_REVISION, LLM не найдет совпадения в своей инструкции и молча пропустит этап доработки.

Как передается контекст при вызове пересмотра

Вызов доработки следует тому же правилу передачи контекста, что и элемент 5: оркестратор должен явно включить все, поскольку у копирайтера нет памяти о своей первой версии:

"I need you to revise the Instagram posts based on critic feedback.

ORIGINAL BRIEF:
[the original user request]

YOUR FIRST VERSION:
[the posts the copywriter created]

CRITIC FEEDBACK (Score: 6/10 - NEEDS_REVISION):
[the critic's specific suggestions]

Please revise the posts addressing this feedback while maintaining
the strengths the critic identified."

Без раздела "YOUR FIRST VERSION" (ТВОЯ ПЕРВАЯ ВЕРСИЯ) копирайтер будет писать с нуля, а не улучшать то, что уже создал.

Почему важно ограничение на одно изменение

После одного раунда доработки координатор передает проект менеджеру проектов независимо от оценки. Инструкция отслеживает это мысленно:

After calling copywriter for revision once:
→ mark "copywriter_revised = true" in context
→ even if the critic still suggests changes, proceed to PM

Без этого ограничения цикл может выполняться бесконечно: Критик отмечает проблему → Копирайтер исправляет → Критик снова отмечает → Копирайтер снова исправляет. Каждый раунд стоит жетонов и времени. Одной проверки достаточно, чтобы улучшить качество без риска зацикливания.

Что передается менеджеру проектов

Менеджер проектов всегда получает окончательные утвержденные версии, а не оригиналы. Если были внесены изменения, оркестратор передает исправленный текст и визуальные элементы. Если все было одобрено с первого раза, то эти объявления сразу же допускаются к показу. Менеджер по продукту никогда не видит отклоненные черновики.

TODO 2 - Register each specialist as a RemoteA2aAgent + AgentTool

Найдите комментарий # TODO 2: For each specialist URL... и замените его следующим кодом:

    if strategist_url:
        available_agents_list.append(
            "- **brand_strategist**: Market research, competitor analysis, trend identification"
        )
        strategist_agent = RemoteA2aAgent(
            name="brand_strategist",
            description="Researches markets, competitors, and trends using Google Search",
            agent_card=f"{strategist_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=strategist_agent))

    if copywriter_url:
        available_agents_list.append(
            "- **copywriter**: Instagram captions, hashtags, and CTAs"
        )
        copywriter_agent = RemoteA2aAgent(
            name="copywriter",
            description="Creates Instagram captions with hashtags and CTAs",
            agent_card=f"{copywriter_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=copywriter_agent))

    if designer_url:
        available_agents_list.append(
            "- **designer**: Visual concepts and real images generated via Gemini (GCS URIs returned)"
        )
        designer_agent = RemoteA2aAgent(
            name="designer",
            description="Creates visual concepts and generates real images via Gemini, stored in GCS",
            agent_card=f"{designer_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=designer_agent))

    if critic_url:
        available_agents_list.append(
            "- **critic**: Quality review with APPROVED/NEEDS_REVISION scoring"
        )
        critic_agent = RemoteA2aAgent(
            name="critic",
            description="Reviews campaign materials and returns structured quality feedback",
            agent_card=f"{critic_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=critic_agent))

    if pm_url:
        available_agents_list.append(
            "- **project_manager**: Project timelines, task breakdowns, Notion integration"
        )
        pm_agent = RemoteA2aAgent(
            name="project_manager",
            description="Creates project timelines and task breakdowns, optionally in Notion",
            agent_card=f"{pm_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=pm_agent))

TODO 3 - Wrap in an App with context compaction

Почему необходимо уплотнение

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

Turn 1:  user prompt                           ~200 tokens
Turn 2:  orchestrator plan                     ~300 tokens
Turn 3:  brand_strategist tool_call            ~150 tokens
Turn 4:  brand_strategist tool_output          ~1,500 tokens  ← full research report
Turn 5:  copywriter tool_call                  ~300 tokens    ← must include strategist output
Turn 6:  copywriter tool_output                ~2,000 tokens  ← 3 captions
Turn 7:  designer tool_call                    ~500 tokens
Turn 8:  designer tool_output                  ~1,500 tokens
...

К моменту, когда за работу берется Агент 4 (Критик), окно контекста содержит полные выходные данные всех трех предыдущих агентов – часто от 8000 до 12 000 токенов только в ответах инструментов. Даже с большим окном контекста Gemini качество рассуждений оркестратора снижается, поскольку ему приходится учитывать постоянно растущую историю. Без сжатия длинные рабочие процессы достигают практических ограничений примерно на четвертом агенте.

Что происходит при уплотнении

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

Without compaction:
  [full strategist output] + [full copywriter output] + [full designer output] + → Critic

With compaction (interval=3, overlap=1):
  [summary of strategist + copywriter] + [full designer output] + → Critic

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

Код

Найдите комментарий # TODO 3: Wrap the agent in an App... и замените плейсхолдер App(...) следующим кодом:

    from google.adk.apps import App
    from google.adk.apps.app import EventsCompactionConfig
    from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
    from google.adk.models import Gemini

    compaction_config = EventsCompactionConfig(
        summarizer=LlmEventSummarizer(llm=Gemini(model_id=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"))),
        compaction_interval=3,   # Summarize after every 3 agent completions
        overlap_size=1,          # Keep the most recent agent's output in full
    )

    app = App(
        name="creative_director",
        root_agent=agent,
        events_compaction_config=compaction_config,
        plugins=[LoggingPlugin()],
    )
    return agent, app

compaction_interval=3 – сжатие выполняется после каждых трех завершений агента. Для конвейера из пяти агентов это означает, что он сработает один раз (после агентов 1–3), а затем критик и менеджер проектов увидят сводку по агентам 1–3 и полные выходные данные предыдущего агента.

overlap_size=1 – последний ответ агента всегда сохраняется дословно и не сокращается. Это важно, потому что Критику нужны все выходные данные Дизайнера, включая значения gcs_uri, чтобы загрузить и проверить изображения. В сводке эти URI будут потеряны.

Как это работает в рамках кампании:

Agent 1 (Strategist)  → full context
Agent 2 (Copywriter)  → full context
Agent 3 (Designer)    → full context
                        ↓ compaction fires: summarizes agents 1-2, keeps 3 in full
Agent 4 (Critic)      → sees [summary of 1-2] + [full output of 3]
Agent 5 (PM)          → sees [summary of 1-3] + [full output of 4]

Что такое RemoteA2aAgent и AgentTool

RemoteA2aAgent("brand_strategist", agent_card=url)
     │
     │  wraps the remote service so ADK can call it
     ▼
AgentTool(agent=strategist_agent)
     │
     │  exposes it as a callable tool to the LLM
     ▼
Agent(tools=[...])
     │
     │  LLM calls tool("brand_strategist", message=...) when needed
     ▼
brand-strategist-xxxx.run.app  ← actual HTTP A2A call happens here

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

Как протестировать Creative Director локально

uv run adk web agents --allow_origins='*'

Откройте Web Preview на порте 8000. В раскрывающемся списке агентов выберите creative_director и попробуйте сделать следующее:

Research the eco-friendly water bottle market for health-conscious millennials

Вы увидите, что креативный директор перенаправит запрос бренд-стратегу, и вы получите ответ от бренд-стратега.

Для всей кампании попробуйте сделать следующее:

Create a complete Instagram campaign for SolarPack portable solar charger targeting
outdoor enthusiasts and digital nomads aged 22-35.
Budget $2,000, launch in 2 weeks.

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

Демонстрация: запуск кампании от начала до конца

Прежде чем продолжить, остановите Creative Director (Ctrl+C), поскольку инспектор A2A также использует порт 8000.

После завершения локального тестирования остановите пять серверов специалистов (Ctrl+C в каждом терминале).

12. Развертывание и тестирование специализированных агентов

Теперь мы готовы развернуть агентов в Google Cloud. Cloud Run – отличный сервис для развертывания агентов. Это бессерверный, масштабируемый и простой в использовании сервис. Каждый агент-специалист развертывается как независимый сервис Cloud Run.

Конфигурация развертывания

Dockerfile каждого специалиста выглядит следующим образом:

FROM python:3.12-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends gcc curl

# Fast dependency install with uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
COPY pyproject.toml .
RUN uv sync --no-install-project --no-dev

COPY . .
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

ENV PYTHONUNBUFFERED=1 PORT=8080 HOST=0.0.0.0
EXPOSE 8080
CMD ["uv", "run", "python", "agent.py"]

Разверните всех 5 специалистов по очереди.

cd ~/ai-creative-studio/workshop/starter
source .env

uv run deploy/deploy_all_specialists.py

Этот скрипт развертывает все пять агентов по одному (всего около 10–12 минут). Последовательное развертывание позволяет избежать превышения квоты на опрос Cloud Build (60 запросов в минуту). После завершения он записывает URL-адрес Cloud Run каждого агента обратно в .env.

После развертывания Designer скрипт автоматически предоставляет сервисному аккаунту Cloud Run роль roles/storage.objectCreator в сегменте GCS, чтобы он мог загружать сгенерированные изображения.

Если вы настроили учетные данные Notion в .env, скрипт также безопасно сохранит их в Secret Manager (как notion-token, notion-project-db-id, notion-tasks-db-id) и внедрит их в сервис менеджера проектов через --set-secrets, а не через простые переменные среды. Это означает, что токен никогда не появится на вкладке среды Cloud Run или в истории команд gcloud.

Проверка развертываний

После завершения развертывания скрипт автоматически записывает URL Cloud Run обратно в .env, заменяя URL localhost из предыдущего шага:

source .env

echo "Deployed URLs:"
echo "  Brand Strategist: $STRATEGIST_AGENT_URL"
echo "  Copywriter:       $COPYWRITER_AGENT_URL"
echo "  Designer:         $DESIGNER_AGENT_URL"
echo "  Critic:           $CRITIC_AGENT_URL"
echo "  Project Manager:  $PM_AGENT_URL"

Creative Director автоматически использует эти URL Cloud Run при развертывании в Agent Runtime на следующем шаге.

Проверка карточек агентов

У каждого развернутого агента есть карточка, доступная по адресу /.well-known/agent.json. Чтобы убедиться, что все работает, выполните следующие действия:

source .env

for agent_url in $STRATEGIST_AGENT_URL $COPYWRITER_AGENT_URL $DESIGNER_AGENT_URL $CRITIC_AGENT_URL $PM_AGENT_URL; do
    echo "=== Agent Card: $agent_url ==="
    curl -s "${agent_url}/.well-known/agent.json" | python3 -m json.tool | grep -E '"name"|"url"|"description"'
    echo ""
done

Ожидаемый результат для каждого агента:

"name": "brand_strategist",
"url": "https://brand-strategist-xxxx.run.app",
"description": "Brand strategist for market research and competitive insights"

Тестирование с помощью A2A Inspector (Cloud Run)

Инспектор A2A уже установлен на шаге 10. Как начать:

cd ~/a2a-inspector
bash scripts/run.sh

Нажмите "Веб-просмотр" → Изменить порт → 5001. В поле подключения введите URL Cloud Run:

https://brand-strategist-xxxx.us-central1.run.app

Нажмите Connect (Подключить). Токен аутентификации не требуется, поскольку сервисы развернуты с помощью --allow-unauthenticated.

Инспектор подключается, проверяет карточку агента и позволяет вам общаться в интерактивном режиме через A2A.

Проверка агентов, развернутых в Cloud Run

После развертывания в Cloud Run укажите в инспекторе общедоступный URL по HTTPS, чтобы проверить, работает ли облачное развертывание:

Инспектор A2A подключен к агенту Cloud Run

Процесс идентичен: вставьте URL Cloud Run, подключитесь и отправьте тестовое сообщение. Если карточка агента загружается и чат отвечает, специалист развернут правильно и доступен.

13. Развертывание Creative Director в Agent Runtime

Оркестратор развертывается в Agent Runtime, который обеспечивает управляемое состояние сеанса, автомасштабирование и встроенную трассировку.

Почему для оркестратора используется Agent Runtime?

Пять специалистов развернуты в Cloud Run – легковесные, без сохранения состояния, каждый из которых выполняет одну задачу. У креативного директора другие требования:

Требования

Почему это важно

Состояние сеанса

Многоэтапный рабочий процесс занимает более 45 секунд. Agent Runtime сохраняет состояние разговора между вызовами инструментов оркестратора, чтобы ничего не потерялось в середине конвейера.

Переменная нагрузка

Иногда по одной кампании в час, иногда несколько параллельно. Среда выполнения агента полностью останавливается, когда не используется, и автоматически масштабируется по горизонтали. Вы не платите за неиспользуемые ресурсы.

Наблюдаемость

Встроенные сервисы Cloud Logging, Cloud Monitoring и Cloud Trace. Вы можете увидеть каждый вызов A2A, каждый использованный токен, каждый всплеск задержки – без добавления каких-либо инструментов.

Длительные рабочие процессы

Время ожидания запроса в Cloud Run составляет 3600 секунд. Agent Runtime предназначена для рабочих процессов, которые могут занимать несколько минут, с управляемыми повторными попытками и сохранением состояния.

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

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

Как развернуть управляющий агент

cd ~/ai-creative-studio/workshop/starter
source .env

uv run deploy/deploy_orchestrator.py --action deploy

Это займет 5–10 минут. После этого AGENT_ENGINE_ID и AGENT_ENGINE_RESOURCE_NAME сохраняются в .env.

source .env
echo "Agent Engine ID: $AGENT_ENGINE_ID"
echo "Resource: $AGENT_ENGINE_RESOURCE_NAME"

Как работает развертывание

client.agent_engines.create() упаковывает объект App, загружает его вместе с зависимостями и развертывает в управляемой инфраструктуре. Вот что означает каждый параметр:

import vertexai
from vertexai import Client, agent_engines

vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

# Wrap the App in an AdkApp adapter - enables tracing in Cloud Trace
adk_app = agent_engines.AdkApp(app=root_app, enable_tracing=True)

# Initialize client and deploy
client = Client(project=PROJECT_ID, location=LOCATION)

agent_engine_resource = client.agent_engines.create(
    agent=adk_app,
    config={
        "staging_bucket": STAGING_BUCKET,   # GCS bucket for packaging artifacts
        "display_name": "Creative Director",
        # Python packages installed in the managed runtime - pin for reproducibility
        "requirements": [
            "google-cloud-aiplatform[agent_engines]>=1.132.0,<2.0.0",
            "google-adk[a2a]==1.31.1",
            "google-genai>=1.70.0",
            "google-cloud-storage>=2.10.0",
            "python-dotenv>=1.0.0",
            "pydantic>=2.0.0",
            "cloudpickle>=3.0.0",
        ],
        # Specialist URLs passed as env vars - the orchestrator reads these at runtime
        "env_vars": {
            "COPYWRITER_AGENT_URL": COPYWRITER_URL,
            "DESIGNER_AGENT_URL":   DESIGNER_URL,
            "STRATEGIST_AGENT_URL": STRATEGIST_URL,
            "CRITIC_AGENT_URL":     CRITIC_URL,
            "PM_AGENT_URL":         PM_URL,
        },
    },
)

resource_name = agent_engine_resource.api_resource.name
agent_engine_id = resource_name.split("/")[-1]

Что происходит в фоновом режиме

1. Agent Engine packages your App + requirements into a container
2. Uploads it to the staging bucket in your project
3. Deploys to managed compute (you never see or manage the VM)
4. Returns a resource name: projects/.../locations/.../reasoningEngines/<id>
5. That ID is saved to .env as AGENT_ENGINE_ID

После развертывания оркестратор подключается к пяти специалистам Cloud Run через URL в переменных среды.

  • Они передаются в .env перед запуском скрипта развертывания.

14. Проведите кампанию от начала до конца

Система развернута полностью. Запустите полную кампанию в тестовой среде Agent Runtime.

Открыть тестовую среду Agent Runtime

  1. Перейдите на страницу https://console.cloud.google.com/agent-platform/runtimes. Вы также можете перейти в среду выполнения агента, выбрав Платформа агентов > Агенты > Развертывания.
  2. Выберите развернутый экземпляр Agent Runtime (creative-director).
  3. Нажмите Playground (Песочница) на боковой панели слева.
  4. Нажмите Новый сеанс, чтобы начать новый чат.

Проведите полную кампанию

Скопируйте этот бриф в чат и отправьте:

Create a complete Instagram campaign for:
- Product: EcoFlow Smart Water Bottle (tracks hydration, keeps drinks cold 24h)
- Target Audience: Health-conscious millennials, 25-35 years old
- Platform: Instagram
- Goal: Brand awareness + drive website traffic
- Brand Voice: Motivational, clean, science-backed
- Budget: $3,000
- Timeline: Launch in 2 weeks

Креативный директор выполнит все пять агентов по очереди:

  1. Специалист по стратегии бренда → исследование рынка, анализ конкурентов, статистика аудитории
  2. Копирайтер → 3 публикации в Instagram с подписями, хештегами и призывами к действию.
  3. Дизайнер – визуальные концепции и реальные изображения, сгенерированные Gemini (URI GCS) для каждой публикации.
  4. Критик – оценка качества с пометками "Одобрено" или "Требуется доработка".
  5. (Revision if needed) → Copywriter or Designer called again with feedback
  6. Менеджер проектов → двухнедельный график, разбивка задач, распределение бюджета.

Демонстрация: запуск кампании с интеграцией Notion

Тестирование маршрутизации с одним агентом

Отправьте этот сокращенный запрос в новом сеансе:

Research the luxury skincare market - top brands and trends for this year.

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

Проверка трассировок выполнения

В консоли администратора:

  1. Нажмите Traces (Трассировки) на боковой панели слева (рядом с Playground).
  2. В разделе Trace View (Просмотр трассировки) выберите трассировку для только что запущенного сеанса.
  3. Разверните дерево трассировки, чтобы посмотреть каждый вызов агента, его входные и выходные данные, задержку и использование токенов.

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

Как запустить приложение из терминала (необязательно)

Вы также можете запустить кампанию программно, используя скрипт run_campaign.py, который уже включен в стартовый пакет.

cd ~/ai-creative-studio/workshop/starter
uv run run_campaign.py

15. Убирать

Удалите ресурсы Google Cloud, чтобы избежать дальнейших расходов.

Запустите скрипт teardown, который считывает файл .env и удаляет все, что было создано в ходе этой практической работы:

bash deploy/teardown_gcp.sh

Скрипт покажет, что именно будет удалено, и запросит подтверждение, прежде чем что-либо делать:

Ресурс

Что будет удалено

Сервисы Cloud Run

brand-strategist, copywriter, designer, critic, project-manager

Agent Runtime

Креативный директор: механизм рассуждений + все сеансы

Artifact Registry

Хранилище cloud-run-source-deploy и все образы Docker

Сегменты GCS

{PROJECT_ID}-campaign-images, {PROJECT_ID}-agent-staging, run-sources-{PROJECT_ID}-{REGION}

Secret Manager

notion-token, notion-project-db-id, notion-tasks-db-id (пропускается, если не создано)

Убедитесь, что все удалено

gcloud run services list --region=us-central1
gcloud storage buckets list --project=$GCP_PROJECT_ID

Ожидаемый результат: пустые списки или только ваши собственные ресурсы.

16. Сводка

Поздравляем! Вы создали и развернули мультиагентную ИИ-систему промышленного уровня в Google Cloud.

Что вы построили

Агент

Возможности

Развертывание

Бренд-стратег

Исследование рынка с помощью Google Поиска

Cloud Run

Копирайтер

Создание подписей для Instagram

Cloud Run

Дизайнер

Генерация изображений с помощью Gemini и загрузка в GCS

Cloud Run

Критик

Проверка качества с оценкой

Cloud Run

Менеджер проектов

Хронология + Notion MCP

Cloud Run

Креативный директор

Полная оркестровка через A2A

Agent Runtime

Основные закономерности, которые вы узнали

  1. ADK Agent – определение LLM-агента с помощью инструкции и дополнительных инструментов.
  2. adk web – запуск и тестирование любого агента ADK локально со встроенным интерфейсом чата.
  3. SkillToolset – упаковывайте знания в модульные файлы, которые можно загружать по запросу.
  4. FunctionTool – оберните любую функцию Python (или внешнюю модель) как вызываемый инструмент агента.
  5. to_a2a() – предоставление доступа к любому агенту ADK как к HTTPS-сервису, совместимому с A2A.
  6. RemoteA2aAgent + AgentTool – управление удаленными агентами как вызываемыми инструментами.
  7. McpToolset – подключение к внешним сервисам через серверы MCP stdio.
  8. EventsCompactionConfig – управление лимитами токенов в длинных рабочих процессах с несколькими агентами.
  9. Структурированные выходные данные критика – машиночитаемый контроль качества с автоматическим пересмотром.
  10. Cloud Run – развертывание контейнеризированных агентов в большом масштабе.
  11. Agent Runtime – размещение оркестраторов с управляемыми сеансами и трассировкой.

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

  • Добавьте в Дизайнер многоэтапное редактирование изображений, используя возможности редактирования gemini-3.1-flash-image.
  • Добавьте аутентификацию IAM в сервисы Cloud Run (удалите --allow-unauthenticated).
  • Замените одного специалиста агентом LangGraph или CrewAI – A2A не зависит от фреймворка.
  • Добавьте инструмент Отзывы пользователей, чтобы участники могли оценивать результаты и вносить изменения.
  • Отслеживание среды выполнения агента в Cloud Console

Ресурсы