Агентные рабочие процессы с ADK

1. Введение

VibeStudio

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

Сценарий

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

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

Рабочий процесс от идеи до публикации клипа.

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

10-summary

  • Основы проектирования графов. Многоэтапные архитектуры агентов требуют явного управления потоком и структурированных путей выполнения. Вы создаете ADK Workflow, используя кортежи ребер, точку входа START, JoinNode для параллельной агрегации с разветвлением и детерминированные узлы маршрутизатора для управления выполнением на основе состояния.
  • Режимы агента и обратные вызовы жизненного цикла. Для выполнения специализированных задач требуются определенные модели поведения и детерминированные ограничения. Вы настраиваете экземпляры ADK Agent, используя режимы chat, single_turn и task с поддержкой инструментов в качестве узлов рабочего процесса, применяя перехватчики с помощью before_model_callback и after_agent_callback.
  • Человек в контуре. Конвейеры производства приостанавливаются на критических контрольных точках, чтобы человек мог оценить результат. Вы реализуете RequestInput, чтобы приостановить выполнение рабочего процесса, применить структурированные схемы ответов и возобновить выполнение, не поддерживая активные процессы среды выполнения в режиме ожидания.
  • Иерархическая память агента. В производственных системах временное состояние выполнения отделяется от постоянного контекста. Вы управляете краткосрочным состоянием сеанса с помощью Event(state=...) и привязки параметров, а также подключаете банк памяти GEAP для извлечения, консолидации и сохранения предпочтений автора между запусками.
  • Обоснование с помощью корпоративных баз знаний. Автономным агентам требуется динамический контекст домена и настроения аудитории. Вы подключаете корпус GEAP RAG Engine в качестве выделенного узла извлечения в параллельной веерной рассылке, чтобы семантически обосновать выходные данные агента.
  • Длительные рабочие процессы и развертывание. Мультимодальный рендеринг видео выполняется асинхронно в течение длительного времени. Вы реализуете LongRunningFunctionTool с ожидающими квитанциями о вызовах, чтобы приостанавливать и возобновлять рабочий процесс по идентификатору вызова, и развертываете готовый конвейер с помощью ADK Runner в Cloud Run.

Структура практической работы

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

Практическая работа выполняется в VibeStudio Workbench – сопутствующем веб-интерфейсе с интерактивным редактором кода, верификаторами среды выполнения и встроенным инспектором ADK. Нумерация шагов в рабочей области соответствует нумерации в codelab, чтобы вы могли отслеживать свой прогресс. Изменения в базовом графе сохраняются на всех этапах, а рабочая область автоматически проверяет необходимые условия по мере вашего продвижения.

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

Что где работает: VibeStudio Workbench, ваш бэкенд и сервисы Google Cloud

Среда состоит из трех основных компонентов: VibeStudio Workbench (локальный веб-интерфейс для редактирования кода и проверки во время выполнения), ваша серверная часть (ADK Workflow и промежуточные песочницы в agent/) и Google Cloud (модели Gemini, банк памяти GEAP, механизм RAG и генерация видео Veo).

2. Настройка

Получите бонус за участие в семинаре

Если вы участвуете в практической работе под руководством инструктора, он распределит бонусы для вашего проекта Google Cloud. Следуйте инструкциям преподавателя, чтобы активировать кредиты и убедиться, что в вашем аккаунте включена оплата.

Открыть Cloud Shell

Cloud Shell – это браузерная среда разработки с предустановленными gcloud, Python и git.

Чтобы запустить Cloud Shell:

  1. Перейдите в Google Cloud Shell.

В нижней части окна браузера откроется сеанс терминала.

Как клонировать и инициализировать репозиторий

Чтобы клонировать проект, выполните в терминале Cloud Shell следующие команды:

git clone https://github.com/gca-americas/vibetube-studio
cd ~/vibetube-studio

Запросы на настройку

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

  • Идентификатор проекта Google Cloud. Когда setup_project.sh предложит создать новый проект, нажмите Ввод. Если вы хотите использовать существующий проект (например, предварительно назначенный), введите идентификатор проекта и убедитесь, что он написан правильно и для него включена оплата.
  • Код мероприятия. Введите код комнаты, предоставленный преподавателем. Если вы не получили его, обратитесь к ассистенту преподавателя или соседу. Если вы выполняете это практическое занятие дома, нажмите клавишу Ввод, чтобы принять комнату по умолчанию sandbox.
  • Отображаемое название канала. Введите имя или псевдоним канала, когда появится запрос от setup_codelab.sh, или нажмите Ввод, чтобы принять имя, сгенерированное на основе вашего аккаунта Google.

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

./setup_project.sh
./setup_codelab.sh
  • setup_project.sh – создает или повторно использует проект Google Cloud с активным платежным аккаунтом, сохраняет идентификатор проекта в ~/project_id.txt и настраивает активный контекст gcloud.
  • setup_codelab.sh: устанавливает uv и зависимости Python в .venv, включает необходимые API Google Cloud, настраивает параметры канала в .env, проверяет доступ к модели с помощью Gemini, инициализирует ресурсы Memory Bank и RAG, создает интерфейс рабочей области и запускает VibeStudio Workbench.

Скрипт выполняет предварительную проверку и запускает VibeStudio Workbench в фоновом режиме. В последних строках будет указана ссылка, которую нужно открыть.

7 · Preflight
  ✓ python 3.12
  ✓ auth path A: Vertex via ADC (STUDIO_VERTEX=1)
  ✓ Google Cloud ADC (project <your-project>)
  ✓ stage0_prompt loads
  ...
  ✓ stage6_video loads (13 edges)
  ✓ aiplatform.googleapis.com enabled (Gemini, Veo, Memory Bank, RAG Engine)
  ✓ vectorsearch.googleapis.com enabled (the vector store a RAG corpus is built on)
  ✓ Memory Bank connected
  ✓ RAG corpus connected
  ✓ VibeStudio Workbench running on port 4600

PREFLIGHT GREEN

Setup finished. The VibeStudio Workbench is already running.

  Open this and start at step 1
      https://4600-<your cloud shell host>/step/story

  It runs in the background. You do not need to start anything else.
      log      runs/lab.log
      stop     kill $(cat runs/lab.pid)
      start    scripts/start.sh

Нажмите на эту ссылку. Тот же адрес доступен в разделе Предпросмотр сайта → Изменить порт → 4600.

Чтобы повторно проверить среду, выполните команду python scripts/preflight.py. Чтобы перезапустить рабочую среду, выполните команду scripts/restart.sh. Чтобы настроить заново, запустите ./setup_codelab.sh. Конфигурация и прогресс будут сохранены.

Открыв его, прочитайте шаг 1, История, чтобы узнать сценарий, и шаг 2, Что вы создаете, чтобы узнать форму готового графика. Ни в одном из них нет упражнений. Затем вернитесь к шагу 3.

Каждая практическая часть VibeStudio Workbench заканчивается панелью проверки, на которой отображаются реальные артефакты: файл на диске и сеансы, записанные во время выполнения.

Структура репозитория

Репозиторий состоит из основной логики рабочего процесса, пошаговых песочниц, среды рабочего места и рабочего приложения:

vibe-studio-lab/
├── agent/                  # Core ADK workflow, graph definition, and platform services
│   ├── graph.py            # Workflow graph definition, node functions, and routers
│   ├── desk.py             # Video render desk using LongRunningFunctionTool
│   ├── schemas.py          # Pydantic schemas for directions, gates, and scripts
│   ├── trends.py           # Trend generation and sampling utilities
│   ├── backlog.txt         # Creator video ideas backlog
│   ├── comments.md         # Audience comments for RAG Engine corpus seeding
│   ├── policy_words.txt    # Blocked subject words for deterministic policy checks
│   └── platform/           # Google Cloud service clients (Memory Bank, RAG, Veo)
│       ├── config.py       # Environment variables, locations, and model configurations
│       ├── memory.py       # GEAP Memory Bank callbacks and context injection
│       ├── rag.py          # GEAP RAG Engine corpus creation and semantic retrieval
│       └── videogen.py     # Veo video generation and operation polling
├── stage0_prompt/          # Step sandboxes: isolated agent.py files runnable in adk web
│   └── ...                 # stage1_fanout through stage6_video for incremental steps
├── server/ & web/          # VibeStudio Workbench (FastAPI backend and React frontend)
├── vibestudio/             # Complete production application deployed to Cloud Run
│   ├── server/             # FastAPI production server and event runner
│   ├── web/                # End-user React web application
  • agent/: содержит основной граф рабочего процесса. Вы будете редактировать файлы в этом каталоге, чтобы реализовать параллельные узлы веерной рассылки, детерминированную маршрутизацию правил, обратные вызовы памяти и инструменты создания видео.
  • agent/platform/ – взаимодействует с сервисами Google Cloud, включая модели Gemini, GEAP Memory Bank, GEAP RAG Engine и Veo.
  • stage0_prompt/ – stage6_video/ – автономные тестовые среды. Каждая папка экспортируется как отдельный файл root_agent, поэтому вы можете запускать и проверять каждый шаг отдельно с помощью встроенного интерфейса разработки ADK.
  • server/ и web/ – приложение VibeStudio Workbench, запущенное локально на порте 4600. Здесь вы найдете документацию по шагам, встроенный редактор кода, средства проверки доказательств среды выполнения и визуализацию графа.
  • vibestudio/: готовое приложение, упакованное и развернутое в Cloud Run на последнем этапе. Она содержит отдельную копию графа завершенного рабочего процесса.

3. Монолитный агент

Прежде чем создавать граф рабочего процесса с несколькими узлами, вы создаете базовую архитектуру с одним агентом в stage0_prompt/agent.py. Этот агент использует монолитный системный запрос, описывающий производственный конвейер в прозе, поддерживаемый двумя инструментами функций Python.

Оценка этого базового уровня демонстрирует операционные границы координации на основе подсказок и объясняет, почему производственным системам требуется оркестровка графов.

Архитектура агента ADK (3A)

В VibeStudio Workbench перейдите к разделу Step 3 · Monolithic agent (Шаг 3. Монолитный агент) и откройте ADK agent architecture (3A) (Архитектура агента ADK (3A)). На этом изображении показаны основные архитектурные уровни агента ADK (LlmAgent):

03-3A

from google.adk.agents import LlmAgent
from google.adk.tools import mcp_toolset

root_agent = LlmAgent(
    model="gemini-3.5-flash",                 # model
    instruction=BRAND_INSTRUCTION,            # instruction
    skills=[load_skill("brand-audit")],       # skills
    tools=[mcp_toolset("mcp_brand_style")],   # tools
    output_schema=BrandStyleReport,           # structured output
    before_agent_callback=setup_ctx,          # interceptor
    before_model_callback=require_image,      # interceptor
    after_model_callback=schema_guard,        # interceptor
)

На интерактивной диаграмме компоненты агента сгруппированы по пяти операционным доменам:

  • Уровень рассуждений (модель). Основная языковая модель (например, Gemini 3 Flash), выполняющая когнитивные задачи, рассуждения на основе запросов и выбор инструментов. Все остальные элементы архитектуры либо влияют на эту модель, либо ограничивают ее.
  • Контекстный уровень (инструкции и навыки). Директивы, которые определяют логику модели. instruction устанавливает постоянные системные подсказки, образ и правила работы. skills содержат пошаговые инструкции (SKILL.md) для повторяющихся рабочих процессов.
  • Уровень взаимодействия и действий (инструменты, вспомогательные агенты, рабочий процесс, схема выходных данных). Интерфейсы, позволяющие агенту выполнять действия во внешних системах и передавать типизированные данные. tools предоставляют вызываемые функции Python или конечные точки Model Context Protocol (MCP). subagents выполнять подчиненные делегированные задачи. workflow координирует графики нескольких агентов. output_schema применяет модели Pydantic, чтобы гарантировать, что последующие потребители получат проверенный JSON вместо неструктурированного текста.
  • Уровень перехватчика (обратные вызовы жизненного цикла). Детерминированные ограничения, которые выполняют пользовательский код до и после выполнения агента (before_agent/after_agent), отдельных ходов модели (before_model/after_model) и вызовов инструментов (before_tool/after_tool). Перехватчики обеспечивают соблюдение правил без необходимости полагаться на соответствие модели.
  • Внешнее состояние (сеанс и память). Сохранение состояния отдельно от логики агента. Session сохраняет временную рабочую память и трассировку событий для текущего потока выполнения. Memory сохраняет факты и предпочтения, которые не зависят от сеанса, используя управляемые сервисы, такие как GEAP Memory Bank.

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

Спецификация монолитного агента (3B)

В рабочей области перейдите к разделу Monolithic agent specification (3B) (Спецификация монолитного агента (3Б)). Откройте stage0_prompt/agent.py, чтобы изучить базовое определение агента:

  • Инструкция в одном запросе. Системный запрос объединяет пять отдельных задач по созданию контента в непрерывный текст: поиск трендов на платформе, анализ идей из бэклога, предложение креативных концепций, применение правил в отношении запрещенных тем и составление списков кадров.
  • Источники данных. Агент ссылается на два источника, указанных рядом с графиком:
    • agent/trends.py: выбирает 10 актуальных трендов в формате и стиле из 250 с динамическими показателями популярности.
    • agent/backlog.txt: читает заметки автора по строкам.

Инструменты в Agent (3C)

В рабочей области перейдите к разделу Инструменты в агенте (3C).

Что такое инструмент для агента?

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

Инструмент позволяет преодолеть это ограничение. Они позволяют модели получать фундаментальную истину и выполнять детерминированные действия во внешних системах.

03-3C

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

  1. Объявление схемы. Разработчик предоставляет агенту функции Python. ADK проверяет название каждой функции, аннотации типов и строки документации, чтобы создать декларацию схемы JSON, совместимую с OpenAPI, которая описывает параметры и назначение функции.
  2. Рассуждения модели. Во время инференса модель оценивает, требуются ли для ответа на запрос пользователя внешние данные. При необходимости модель генерирует структурированное событие function_call, содержащее название целевой функции и словарь аргументов, соответствующий схеме.
  3. Выполнение кода. Модель не выполняет код сама. Среда выполнения ADK перехватывает function_call, выполняет локальную функцию Python с предоставленными аргументами и фиксирует возвращаемое значение.
  4. Повторное внедрение контекста. Среда выполнения ADK упаковывает возвращаемое значение функции в событие function_response и добавляет его в историю активного сеанса.
  5. Окончательный синтез. Модель обрабатывает выходные данные инструмента, которые теперь находятся в окне контекста, и завершает ответ.

В stage0_prompt/agent.py два инструмента для исследований определены как стандартные функции Python:

def check_trends() -> dict:
    """Ten formats trending on the platform right now, with a heat score each."""
    from agent.trends import sample_trends
    return {"trends": sample_trends()}


def read_backlog() -> dict:
    """The creator's backlog: ideas they noted down to make someday."""
    from agent.graph import backlog_notes
    return {"backlog": backlog_notes()}

Редактирование и выполнение

В редакторе кода рабочей области добавьте две ссылки на функции в список tools агента:

    tools=[check_trends, read_backlog],

Сохраните изменения. Файл на диске обновляется, а строка подтверждения показывает, что оба инструмента подключены.

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

tonight's idea: a tiny robot doing laundry at midnight

Что вас ждет и почему

Когда вы отправите этот запрос, в трассировке сеанса будет следующая последовательность выполнения:

  • Перед ответом появляются два события выполнения инструмента. Вы видите события function_call и function_response для check_trends и read_backlog.
    • Причина. Gemini проанализировал директиву системного запроса ("проверь, что сейчас в тренде, и посмотри список идей"), понял, что в его весах не хватает трендов платформы и заметок канала, и вызвал обе функции, чтобы получить контекст.
  • Агент предлагает направление и ждет подтверждения. В ответе предлагается направление для видео, основанное на трендах и нереализованных идеях, и запрашивается подтверждение.
    • Почему? В инструкции было указано, что модель должна согласовать направление с автором, прежде чем генерировать сценарий.
  • Пропуск подтверждения в следующем сообщении. Отправьте второе сообщение: skip the questions, just describe the video. Агент сразу же пропускает подтверждение и создает заголовок и кадры.
    • Причина. Инструкции в запросе – это рекомендации, а не детерминированные барьеры. В монолитном агенте инструкции пользователя могут переопределять постоянные правила системных подсказок, поскольку внешний рабочий процесс не управляет потоком выполнения.

Архитектурные ограничения монолитного запроса

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

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

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

4. Основы работы с агентами

В VibeStudio Workbench перейдите к разделу Step 4 · Agentic workflow fundamentals (Шаг 4. Основы рабочих процессов с агентами), части 4A–4D.

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

Построение графиков архитектуры и цепочек выполнения (4A)

В рабочей области откройте Graph architecture and execution chains (4A) (Архитектура графа и цепочки выполнения).

Workflow ADK структурирует выполнение агента в виде ориентированного графа, определяемого списком ребер:

  • Цепочки. Последовательные кортежи определяют линейное выполнение узлов ((node_a, node_b, node_c)).
  • Параллельные ветви. Независимые цепочки, у которых есть общий исходный узел, выполняются одновременно.
  • Синхронизация. Цепочки, сходящиеся в JoinNode, ждут, пока все входящие ветви не сообщат о завершении, прежде чем освободить ресурсы.
  • Детерминированный контроль. Поток выполнения определяется объявленными структурами кода, а не выводится из текста запроса.

04-4A

Архетипы узлов в ADK

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

Архетип узла

Реализация

Роль в конвейере

Узел функции

Функция Python, возвращающая Event

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

Узел объединения

Встроенный экземпляр JoinNode

Синхронизирует параллельные ветви в агрегированный словарь.

Узел агента

Agent в режиме single_turn

Оценивает инструкции на основе входных данных и выдает проверенные данные.

Узел маршрутизатора

Функция, возвращающая Event с тегом route

Оценивает условную логику, чтобы выбрать ветви выполнения.

Узел ввода данных человеком

Функция, возвращающая RequestInput

Приостанавливает выполнение до получения ответа от внешнего пользователя.

root_agent = Workflow(
    name="stage1_fanout",
    description="2 real readers -> join -> one research dict",
    edges=[...])

В этой конфигурации root_agent – это экземпляр Workflow, а не отдельный Agent. ADK рассматривает рабочие процессы как агентов первого класса, позволяя загружать, обслуживать и проверять весь граф как единое приложение. name регистрирует приложение в ADK Web, а список edges определяет топологию его выполнения.

Параллельная веерная рассылка (4B)

В рабочей области перейдите к разделу Параллельный поиск (4B). Откройте stage1_fanout/agent.py.

04-4B

Узлы функций и барьеры синхронизации

На этапе исследования используются два узла функций, импортированных из agent/graph.py:

  • scan_trends: возвращает Event(output={"trends": [...]}), содержащий десять трендов платформы с оценками.
  • read_backlog: возвращает Event(output={"backlog": [...], "idea": "..."}) с 15 идеями для канала и исходным запросом.

Каждая функция принимает node_input (выходные данные предыдущего узла) и возвращает Event.

JoinNode служит барьером синхронизации: он приостанавливает работу, пока каждая входящая цепочка не доставит событие, а затем агрегирует все результаты ветвей в словарь с ключами по имени узла ({"scan_trends": {...}, "read_backlog": {...}}).

Практическое задание: определение соединения и параллельных ребер

В файле stage1_fanout/agent.py создайте экземпляр JoinNode и подключите две параллельные цепочки, начиная с START:

join_research = JoinNode(name="join_research")
    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research)])

Сохраните изменения. Проверьте, что соединения и края проводные. Запустите этап с помощью команды Run Stage 1 или через встроенный веб-интерфейс ADK.

Что дальше и почему

  • Одновременное выполнение операций чтения. На графике выполнения scan_trends и read_backlog выполняются одновременно.
    • Причина изменений. Обе цепочки начинаются с START. Движок ADK планирует независимые ветви одновременно.
  • Сводный словарь. Рабочий процесс завершается в точке join_research, и на выходе получается словарь с записями для обоих читателей.
    • Зачем это нужно. JoinNode обеспечивает полный сбор данных, прежде чем разрешить выполнение последующих узлов.

Узлы агентов (4C)

В рабочей области перейдите к разделу Узлы агента (4C). Откройте stage2_direction/agent.py.

04-4C

Режимы работы и структурированные схемы

Если код Agent встроен в код Workflow, по умолчанию он выполняется в режиме single_turn:

  • Он получает выходные данные предыдущего узла в качестве входных данных контекста.
  • Он выполняет один вызов логического вывода без диалога.
  • Он передает структурированные данные следующему узлу.

Присваивая output_schema=Directions, агент применяет валидацию Pydantic к выходным данным модели. Входящий граф получает типизированные объекты вместо неструктурированного текста:

class Direction(BaseModel):
    title: str           # <=60 chars, filmable, characterful
    angle: str           # the twist, one line
    hook: str = ""       # 2-4 words, the video's sticker line
    evidence: list[Evidence]


class Directions(BaseModel):
    candidates: list[Direction]   # exactly 4

PROPOSE_INSTRUCTION directs the model to propose four candidates citing evidence from both the trends and the backlog. Кандидаты 1–3 предлагают жизнеспособные концепции каналов. Кандидат 4 намеренно вводит концепцию, нарушающую правила, чтобы проверить шлюз безопасности на следующем шаге.

Практическое задание: определение узла агента и объединение в цепочку

В stage2_direction/agent.py настройте propose_directions и расширьте границы рабочего процесса:

propose_directions = Agent(
    name="propose_directions",
    model=config.MODEL,
    instruction=PROPOSE_INSTRUCTION,
    output_schema=Directions)
    edges=[(START, scan_trends, join_research),
           (START, read_backlog, join_research),
           (join_research, propose_directions, direction_gate)])

Что дальше и почему

  • Прямое использование словаря. propose_directions использует полезную нагрузку JSON, созданную join_research, без ручного форматирования.
  • Типизированный вывод кандидатов. Агент выдает проверенный объект Directions, содержащий четыре отдельных кандидата. Дочерние узлы считывают поля по названию атрибута (candidate.title) без синтаксического анализа строк.

Человек в контуре (4D)

В рабочей области перейдите к разделу Человек в контуре (4D). Откройте agent/graph.py.

04-4D

Инструкции для запросов и детерминированная блокировка

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

  • Функция yield RequestInput немедленно приостанавливает выполнение рабочего процесса.
  • ADK регистрирует вызов прерывания в хранилище сеансов и выдает уникальный interrupt_id.
  • Процесс выполнения останавливается без использования токенов или серверных потоков.
  • Выполнение графа возобновляется только после отправки действительного объекта function_response, соответствующего схеме и идентификатору прерывания.

Практическое занятие по редактированию: приостановка выполнения с помощью RequestInput

В agent/graph.py реализуйте вызов приостановки внутри direction_gate:

    yield RequestInput(
        message="Pick tonight's direction: 1, 2, 3 or 4.",
        response_schema={
            "type": "object",
            "properties": {
                "pick": {"type": "string", "enum": ["1", "2", "3", "4"]}}},
        payload={"candidates": cands})

RequestInput настраивает три атрибута:

  • message – запрос отзыва, показанный пользователю.
  • response_schema – схема JSON, которую интерфейс отображает как форму ввода, проверяемую ADK при отправке.
  • payload – метаданные, связанные с запросом (четыре варианта), которые позволяют интерфейсам клиентов показывать карточки отзывов без запроса состояния сеанса.

Что вас ждет и почему

  • Рабочий процесс останавливается на этапе direction_gate. В веб-интерфейсе ADK или рабочей области выполнение приостанавливается и появляется интерактивная форма выбора кандидата.
    • Причина. Система обнаружила RequestInput и сохранила состояние выполнения в runs/sessions.db.
  • Для возобновления требуется структурированный ввод. Отправка произвольного текста чата не продвигает граф. При выборе варианта (1, 2, 3 или 4) отправляется введенное значение function_response, которое соответствует response_schema, и выполнение возобновляется.

5. State и Router

В VibeStudio Workbench перейдите к Step 5 · State and Router (Шаг 5. Состояние и маршрутизатор), части (5A)–(5C).

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

Статус рабочего процесса (5A)

В рабочей области перейдите к разделу Workflow State (5A) (Состояние рабочего процесса (5A)).

05-5A

Состояние сеанса и выходные данные узла

В рабочем процессе ADK данные перемещаются по графу с помощью двух разных механизмов:

  • Выходные данные узла (Event(output=...)). Данные, направляемые непосредственно потребителям, которые указаны в списке ребер.
  • Состояние сеанса (Event(state=...)). Общий словарь ключ-значение, доступный любому последующему узлу в жизненном цикле выполнения.

05-5A

Когда пользователь выбирает вариант в direction_gate, выбор поступает в виде числового индекса ({"pick": "2"}). Последующим узлам нужен полный объект направления: заголовок, угол повествования и зацепка. Вместо того чтобы передавать подробные метаданные через полезную нагрузку каждого промежуточного узла, persist_direction записывает разрешенного кандидата в общее состояние сеанса.

Узлам не нужно передавать весь словарь состояния сеанса. Когда узел возвращает значение Event(state=...), он предоставляет только новые или обновленные пары "ключ-значение". ADK автоматически объединяет эти обновления в хранилище сеансов:

    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})

При этом Event передает управление среде выполнения Workflow, которая сохраняет новые значения в журнале сеанса в runs/sessions.db.

Привязка параметров

Узлы функций ADK автоматически считывают состояние сеанса, проверяя параметры. Если в сигнатуре функции указано название параметра, совпадающее с названием существующего ключа состояния, ADK извлекает этот ключ из состояния и передает его напрямую:

def persist_direction(node_input, candidates: list = []):
    ni = node_input if isinstance(node_input, dict) else {}
    raw = ni.get("pick")
    pick = str(raw).strip() if raw is not None else ""
    if candidates:
        i = int(pick) - 1 if pick.isdigit() else 0
        chosen = candidates[max(0, min(len(candidates) - 1, i))]
    else:
        chosen = {"title": "untitled", "angle": "", "evidence": []}
    hook = chosen.get("hook") or " ".join(chosen["title"].split()[:4])

В этом примере candidates записывается в состояние сеанса с помощью direction_gate. ADK напрямую связывает его с persist_direction(node_input, candidates: list = []), не требуя явного поиска по словарю.

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

Практическое задание: сохранение состояния и подключение узла

  1. В файле agent/graph.py внутри persist_direction замените строку TODO: PERSIST_STATE на следующую:
    yield Event(state={"direction": chosen["title"], "angle": chosen.get("angle", ""),
                       "hook": hook, "user:prefs": {"last_direction": chosen["title"]}})
  1. В stage3_router/agent.py добавьте persist_direction в третью цепочку в списке edges:
           (join_research, propose_directions, direction_gate,
            persist_direction)

Сохраните файлы. Убедитесь, что в рабочей области рядом с пунктами state write in place и persist_direction in the chain стоят зеленые флажки.

Узел маршрутизатора (5Б)

В рабочей области перейдите к узлу The router node (5B).

05-5B

Детерминированная маршрутизация на основе правил

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

Маршрутизатор возвращает Event с тегом route:

def length_check(node_input):
    too_long = len(node_input.get("title", "")) > 60
    return Event(output=node_input, route="TRIM" if too_long else "PASS")

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

    (length_check, {"TRIM": shorten, "PASS": scripter}),

Маршрутизатор рабочих процессов policy_check считывает запрещенные фразы из agent/policy_words.txt и выполняет сопоставление целых слов с названием и углом выбранного направления:

    return Event(output=node_input, route="BLOCK" if bad else "OK")

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

Целевые сервисы: Scripter и Quarantine

Маршрутизатор направляет трафик на один из двух узлов:

  • scripter – узел агента single_turn, который преобразует утвержденное направление в структурированный сценарий производства, соответствующий схеме Script Pydantic:
scripter = Agent(
    name="scripter",
    model=config.MODEL,
    instruction=SCRIPT_INSTRUCTION,
    output_schema=Script)
  • quarantine – изначально функция-плейсхолдер, которая останавливает помеченные инструкции, а в следующей части заменяется автономным агентом исправления.

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

  1. В файле agent/graph.py внутри функции policy_check добавьте оператор return:
    return Event(output=node_input, route="BLOCK" if bad else "OK")
  1. В файле stage3_router/agent.py измените edges, чтобы перенаправить policy_check и снова объединить ветвь карантина с scripter:
           (join_research, propose_directions, direction_gate,
            persist_direction, policy_check),
           (policy_check, {"OK": scripter, "BLOCK": quarantine}),
           (quarantine, scripter)])

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

Режимы агента и узел задачи (5C)

В рабочей области перейдите в раздел Режимы агента и узел задачи (5C).

05-5C

Режимы выполнения агента

Экземпляры ADK Agent поддерживают три режима выполнения, адаптированных к конкретным требованиям конвейера:

Режим

Жизненный цикл выполнения

Роль в конвейере

chat

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

Корневые агенты, взаимодействующие с пользователем.

single_turn

Вызов инференса одной модели. Принимает входные данные предыдущего узла и выдает структурированный объект схемы.

Последовательные преобразования графа (propose_directions, scripter).

task

Автономный цикл с выполнением инструмента. Агент выполняет итерации, пока не вызовет встроенный инструмент finish_task.

Многоэтапная проверка и устранение проблем (quarantine).

Автономное устранение нарушений правил

Для переписывания помеченной инструкции требуется режим task, поскольку количество итераций исправления может быть разным. Агент получает отмеченную инструкцию, вызывает find_policy_hits для обнаружения нарушений, запрашивает одобренные альтернативы через suggest_replacement, переписывает инструкцию и проверяет ее на соответствие правилам, прежде чем продолжить.

Оба инструмента определены в agent/cleanup_tools.py с типизированными сигнатурами и строками документации:

def find_policy_hits(text: str) -> dict:
    """Which refused words appear in `text`. Matches whole words and phrases
    from agent/policy_words.txt, case-insensitive.

    Returns {"hits": [...], "clean": bool}. clean is true when hits is empty.
    """


def suggest_replacement(word: str) -> dict:
    """The channel's approved stand-in for a refused word, read from
    agent/policy_replacements.txt.

    Returns {"word", "replacement", "listed"}. When the word has no entry,
    listed is false and replacement is a hint to pick a gentle synonym.
    """

Практическое задание: сборка агента для задач карантина

В файле stage3_router/agent.py замените плейсхолдер функции quarantine на определение агента задач:

quarantine = Agent(
    name="quarantine",
    model=config.MODEL,
    instruction=QUARANTINE_INSTRUCTION,
    mode="task",
    tools=[find_policy_hits, suggest_replacement],
    output_schema=CleanedDirection,
)

В режиме задач агент получает инструменты и завершает выполнение, вызывая finish_task. Когда настроен mode="task", ADK автоматически предоставляет finish_task и получает его параметры из output_schema, обеспечивая, чтобы узел возвращал типизированный объект CleanedDirection, соответствующий входной схеме узла скрипта.

05-5C

Что дальше и почему

Проверьте оба варианта выполнения в ADK Web или VibeStudio Workbench:

  • Одобренный маршрут (кандидат 1, 2 или 3):
    • Выбор одобренного маршрута-кандидата направляет из policy_check напрямую в scripter (route="OK").
    • Скриптер генерирует скрипт из трех кадров, соответствующий схеме Script.
  • Маршрут устранения проблем с карантином (вариант 4):
    • Вариант 4 содержит помеченную лексику ("кликбейт", "вирусный лайфхак").
    • Количество маршрутов в пункт "quarantine" (route="BLOCK"): policy_check.
    • В трассировке сеанса видно, что quarantine вызывает find_policy_hits, вызывает suggest_replacement для каждого нарушения, переписывает заголовок и вызывает finish_task.
    • Выполнение возвращается к scripter, создавая скрипт на основе проверенных указаний.

6. Банк памяти

В VibeStudio Workbench перейдите к шагу 6 "Банк памяти", частям (6A) и (6B).

В настоящее время рабочий процесс не сохраняет информацию между сеансами. Каждый раз все начинается с нуля, и ИИ не знает, что выбирал автор ранее и какие жанры ему нравятся. На этом шаге вы подключите Vertex AI Agent Engine Memory Bank, чтобы хранить и извлекать настройки авторов между запусками.

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

Memory Bank (6A)

На верстаке перейдите к банку памяти (6A).

06-6A

Управляемая память на уровне пользователя

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

SCOPE = {"app_name": config.APP, "user_id": config.USER}
TOPICS = {
    "CREATOR_TASTE": "Which video directions this creator picks and passes on, "
                     "and how that preference changes over time.",
    "CHANNEL_RULES": "Standing instructions the creator states for every video "
                     "(style, subjects to avoid, format rules).",
}

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

  • Извлечение тем. Когда новый текст разговора отправляется через memories.generate, сервис применяет модель извлечения к описанию каждой темы. Если текст не соответствует теме, воспоминания не создаются.
  • Объединение и дедупликация. Сервис преобразует новые факты во встраивания и сравнивает их с существующими воспоминаниями в области видимости. Если наблюдение соответствует существующему воспоминанию, сервис обновляет его. Если информация новая, сервис создает новую запись. Это позволяет объединить несколько сеансов на одну тему в единый пересказ, а не создавать повторяющиеся записи.
  • Получение. При вызове memories.retrieve с областью действия пользователя возвращаются сохраненные факты, упорядоченные по времени добавления (от старых к новым).

Обе операции реализованы в agent/platform/memory.py. Название ресурса банка, подготовленного к работе, сохраняется локально в runs/memorybank.json.

Как настроить банк памяти

Используйте элементы управления рабочей среды или выполните команды CLI в терминале:

  1. Подключите и настройте банк:
    python -m agent.platform.bank
    
    Создает экземпляр Agent Engine и настраивает темы CREATOR_TASTE и CHANNEL_RULES.
  2. Исходные сеансы
    python -m agent.platform.bank load
    
    Загружает четыре сеанса создания тем (две темы с животными и ограничениями по стилю, одна тема с гаджетами и одна недавняя тема в стиле фэнтези).
  3. Просмотр сводных фактов
    python -m agent.platform.bank list
    
    Проверьте результат. Обратите внимание, как повествовательные расшифровки были преобразованы в структурированные, обобщенные утверждения фактов.

Обратные вызовы (6B)

На панели инструментов перейдите в раздел Обратные вызовы (6B). Откройте stage4_memory/agent.py.

06-6A

Обратные вызовы жизненного цикла агента ADK

Обратный вызов – это функция, переданная в качестве аргумента в Agent. ADK вызывает обратные вызовы в заранее определенные моменты жизненного цикла, передавая активный контекст. Если функция возвращает значение None, выполнение продолжается в обычном режиме. Если она возвращает заменяющий объект, операция переопределяется или перехватывается.

06-6A

ADK предоставляет три пары обратных вызовов:

Пара обратного вызова

Точка вызова

Полученные параметры

Поведение при возврате значения

before_agent_callback
after_agent_callback

Вокруг всего хода агента

CallbackContext (состояние, сеанс, вызов)

При нажатии кнопки "Назад" Content ответ агента заменяется, а при нажатии кнопки "Далее" None все происходит как обычно.

before_model_callback
after_model_callback

Окружение каждого вызова вывода LLM

LlmRequest или LlmResponse

Возврат LlmResponse перехватывает или пропускает вызов модели; None продолжает выполнение.

before_tool_callback
after_tool_callback

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

Определение инструмента, аргументы, результат

Возврат словаря переопределяет выходные данные инструмента; None продолжается.

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

Практическое задание: подключение обратных вызовов для отзыва и запоминания

  1. В файле stage4_memory/agent.py обновите propose_directions, чтобы прикрепить before_model_callback=recall_taste:
    output_schema=Directions,
    before_model_callback=recall_taste)

recall_taste выполняется непосредственно перед тем, как Gemini генерирует варианты направлений. Он извлекает историю автора из банка памяти, форматирует воспоминания, начиная с самых старых, и добавляет их к исходящему LlmRequest. Запрос указывает модели, что варианты 1–3 должны быть ближе к текущему вкусу автора, а правила канала – строгими ограничениями.

  1. В stage4_memory/agent.py обновите scripter, чтобы прикрепить after_agent_callback=remember_pick:
    output_schema=Script,
    after_agent_callback=remember_pick)

remember_pick ходит после того, как scripter завершит свой ход. Она считывает выбранное направление из состояния сеанса, синтезирует краткое утверждение, обобщающее решение автора, и вызывает memories.generate для обновления банка памяти.

Что вас ждет и почему

Протестируйте рабочий процесс с обратным вызовом в Workbench или ADK Web:

  1. Выполните запуск с пустым запросом:
    • В трассировке сеанса проверьте LlmRequest для propose_directions. Обратите внимание на добавленный контекст памяти, в котором подробно описываются предпочтения автора в отношении фэнтезийных тем и краткого темпа.
    • Обратите внимание на предложенные направления: кандидаты 1–3 соответствуют историческим предпочтениям автора, даже если тренды подчеркивают другие темы.
  2. Выберите кандидата на сайте direction_gate.
  3. После завершения scripter проверьте записи в банке памяти:
    python -m agent.platform.bank list
    
    Теперь в банке отражается последний выбор, объединенный с предыдущими записями о вкусах.

7. RAG Engine

В VibeStudio Workbench перейдите к Step 7 · RAG Engine (Шаг 7. Движок RAG), части (7A) и (7B).

07-7A

Опубликованные видео получают отзывы зрителей. В файле agent/comments.md собрано 30 комментариев, отражающих похвалу зрителей, критику темпа рекламных вставок и предпочтения в отношении звука. На этом шаге вы проиндексируете комментарии с помощью Vertex AI RAG Engine и подключите семантический поиск к веерной рассылке.

Извлечение данных из документов (7A)

В рабочей области перейдите к разделу RAG Engine (7A) (Механизм RAG (7A)).

Банк памяти и движок RAG

Оба инструмента используют внешние данные, но служат разным целям:

Параметр

Банк памяти

RAG Engine

Основной пример использования

Долгосрочные предпочтения пользователей и правила работы

Семантический поиск по большим коллекциям документов.

Область действия

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

Область действия ограничена общими ресурсами корпуса для всех пользователей.

Обработка данных

Извлечение, эмбеддинг и семантическая консолидация в реальном времени

Разбиение документов на фрагменты, векторное встраивание и поиск ближайших соседей

Интеграция с графиками

Обратные вызовы жизненного цикла агента (before_model_callback, after_agent_callback)

Специализированный узел функций в веерной рассылке исследований (read_feedback)

07-7A

Разбиение документов на фрагменты и эмбеддинги

RAG Engine индексирует документы, разделяя текст на семантические фрагменты и сохраняя их векторы в управляемой базе данных.

corpus = rag.create_corpus(
    display_name="vibestudio-feedback",
    description="Vibe Studio: what the audience wrote under the channel's past videos.",
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=rag.RagEmbeddingModelConfig(
            vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
                publisher_model="publishers/google/models/text-embedding-005"))))

rag.upload_file(
    corpus_name=corpus.name, path="agent/comments.md", display_name="comments.md",
    transformation_config=rag.TransformationConfig(
        chunking_config=rag.ChunkingConfig(chunk_size=120, chunk_overlap=20)))
  • Размер фрагмента: 120 токенов с 20 токенами перекрытия. Это позволяет захватить два-три комментария на отрывок, гарантируя, что каждый вектор представляет собой связное мнение, не размывая смысл несвязанных отзывов.
  • Модель встраивания. text-embedding-005 преобразует текст в многомерные векторы. Когда пользователь вводит запрос, модель преобразует его в вектор и находит ближайшие совпадения на основе семантического расстояния. Комментарий о крошечном драконе, охраняющем носки, соответствует запросу о волшебных существах, даже если в нем нет точного совпадения по ключевым словам.

Как настроить корпус RAG

Инициализируйте корпус, используя кнопки рабочей области или команды терминала:

  1. Создайте корпус:
    python -m agent.platform.rag
    
    Инициализирует управляемую векторную базу данных и записывает идентификатор ресурса в runs/ragcorpus.json.
  2. Загрузка и индексирование комментариев. Загружает agent/comments.md с конфигурацией фрагментации и ожидает завершения индексирования.
  3. Запрос к корпусу. Протестируйте поиск по сходству с запросами, которые не содержат точных слов из комментариев (например, запрос "маленькие волшебные существа" для получения комментариев о драконах).

Узел извлечения (7B)

В рабочей области перейдите к третьему читателю (7B). Откройте stage5_rag/agent.py.

07-7B

Получение в виде узла графа

Отзывы аудитории – это данные исследований, которые передаются в рамках рабочего процесса. В отличие от личных воспоминаний автора, мнения зрителей поступают напрямую в join_research вместе с данными о трендах и невыполненных задачах. Поэтому он реализован как узел функции:

07-7B

def read_feedback(node_input):
    """The third reader (step 7): what the audience wrote under past videos,
    the passages nearest to tonight's idea. Retrieval, not a model call."""
    from .platform import rag
    idea = idea_text(node_input)
    query = idea or "what viewers liked and what they complained about"
    try:
        hits = rag.retrieve(query)
    except Exception as e:
        print(f"  [rag] feedback unavailable ({str(e)[:80]})")
        return Event(output={"query": query, "feedback": [],
                             "note": "no corpus connected - run: python -m agent.platform.rag"})
    return Event(output={"query": query, "feedback": [h["text"] for h in hits]})

read_feedback извлекает исходную идею пользователя и выполняет векторный запрос к корпусу RAG Engine. Извлеченные комментарии передаются в полезной нагрузке Event(output=...).

Практическое задание: подключение третьего считывателя к разветвителю

В файле stage5_rag/agent.py измените edges, чтобы добавить read_feedback в качестве третьей параллельной ветви, входящей в join_research:

           (START, read_backlog, join_research),
           (START, read_feedback, join_research),

Поскольку join_research – это JoinNode, он синхронизирует все входящие ветви, ожидая, пока scan_trends, read_backlog и read_feedback не передадут события, прежде чем передать агрегированный пакет дальше.

Что дальше и почему

Запустите рабочий процесс в рабочей области:

  1. Введите запрос, например "маленький дракон, охраняющий кухонную столешницу".
  2. В трассировке выполнения убедитесь, что все три узла чтения выполняются одновременно.
  3. Посмотрите на join_research: теперь в выходном словаре есть trends, backlog и feedback.
  4. Проверьте варианты, созданные propose_directions. Модель учитывает комментарии зрителей и ссылается на их настроение в полях с доказательствами.
  5. Обратите внимание, что извлечение RAG является детерминированным (одинаковые запросы возвращают одинаковые фрагменты комментариев), тогда как узел генеративных предложений создает креативные варианты.

8. Асинхронное создание видео с помощью Veo

В VibeStudio Workbench перейдите к Step 8 · The video (Шаг 8. Видео), части (8A) и (8B).

На создание видео в высоком разрешении с помощью Google Veo уходит несколько минут. Блокировка выполнения графа в этот период приводит к потере вычислительных ресурсов, блокировке пулов потоков и подвергает запуск риску сбоев HTTP-соединения. На этом этапе вы сделаете рендеринг видео асинхронным с помощью метода LongRunningFunctionTool из ADK.

Инструменты, работающие в течение длительного времени (8A)

На панели инструментов выберите Инструмент, работающий долго (8A). Откройте stage6_video/agent.py и agent/deliver.py.

08-8A

Синхронные инструменты и инструменты, выполняемые долго

Стандартные инструменты ADK выполняются синхронно в рамках одного хода агента: модель вызывает инструмент, ожидает возврата полезной нагрузки и включает результат в текущий ход.

Рендеринг видео не может быть выполнен за один шаг. Вместо этого render_submit инициирует задание по созданию и сразу возвращает квитанцию со статусом "pending":

def render_submit(prompt: str) -> dict:
    """Submit one Veo render of `prompt`. Returns at once with a pending
    receipt; the clip is delivered later, to this call, by id."""
    receipt = videogen.start(f"{prompt} {videogen.NO_TEXT}")
    return {"status": "pending", "operation": receipt["operation"], "prompt": receipt["prompt"]}

Если используется LongRunningFunctionTool, ADK перехватывает статус "pending". Ход агента завершается, рабочий процесс приостанавливается в узле, а метаданные ожидающего вызова (включая идентификатор вызова и квитанцию) записываются в runs/sessions.db. Процесс выполнения завершается без ошибок, не поддерживая активные сетевые подключения или рабочие потоки.

Практическое задание: обертка для инструмента рендеринга

В файле stage6_video/agent.py обновите render_desk, чтобы обернуть render_submit в LongRunningFunctionTool:

    tools=[LongRunningFunctionTool(render_submit)])

Возобновление по идентификатору вызова

Универсальный шаблон возобновления

ADK применяет одинаковый механизм для приостановки и возобновления рабочих процессов как для людей, так и для внешних инструментов:

Причина блокировки

Инициирование конструкта

Состояние приостановки хранения

Событие возобновления

Решение специалиста

yield RequestInput(...)

Открыть запрос на ввод в хранилище сеансов

FunctionResponse с идентификатором вызова приостановки

Инструмент, выполняющий длительные задачи

LongRunningFunctionTool(...) возвращается в pending

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

FunctionResponse с идентификатором вызова приостановки

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

Практическое задание: завершение ответа на вопрос о доставке

В agent/deliver.py создайте часть FunctionResponse для возобновления:

    part = Part(function_response=FunctionResponse(
        id=row["call_id"], name=row["name"], response=response))

Демон доставки опрашивает Veo, пока не будет создан видеофайл, а затем отправляет FunctionResponse в сеанс. ADK сопоставляет идентификатор вызова и возобновляет рабочий процесс непосредственно на следующем узле. Завершенные узлы не выполняются повторно, и агент не переходит к следующему этапу генерации.

Если задать для STUDIO_REAL_VIDEO=0 значение .env, будет включена имитация отрисовки: start сразу возвращает тестовый чек, а check имитирует завершение через пять секунд без платных вызовов Veo API.

Интеграция конвейера (8B)

В рабочей области перейдите к render_desk in the graph (8B). Откройте stage6_video/agent.py.

Конечный узел в конвейере – store_video. Она считывает информацию о завершенном рендеринге из runs/state.json (где ее записал процесс доставки) и фиксирует URL видео и статус генерации в общем состоянии сеанса.

08-8B

Практическое редактирование: подключение полного видеоконвейера

В файле stage6_video/agent.py добавьте в edges строки render_desk и store_video:

           (quarantine, scripter),
           (scripter, render_desk, store_video)])

Что вас ждет и почему

Протестируйте асинхронную генерацию в рабочей области:

  1. Выполните рабочий процесс, выбрав кандидатов и создав скрипт.
  2. В render_desk агент вызывает render_submit.
  3. Рабочий процесс будет немедленно приостановлен. В Workbench или ADK Web проверьте статус ожидания: сеанс содержит идентификатор открытого вызова, а фоновые процессы не потребляют ресурсы.
  4. Запустите демон доставки в консоли Workbench или в терминале:
    python -m agent.deliver
    
    Процесс доставки отслеживает Veo, пока видео не будет готово, а затем отправляет событие возобновления.
  5. В ADK Web обновите сеанс: выполнение возобновится на шаге store_video, URL видео будет зафиксирован в состоянии сеанса, и рабочий процесс завершится.

9. Развертывание в Cloud Run

В VibeStudio Workbench перейдите к шагу 9 "Развертывание".

Вы разработали и проверили каждый компонент конвейера в отдельных изолированных средах. На этом этапе вы собираете полный рабочий конвейер и развертываете его в Google Cloud Run.

09-9A

ADK Runner

В процессе разработки adk web координировал работу над графом. В рабочей среде приложение размещает рабочий процесс с помощью класса Runner из ADK:

self._svc = DatabaseSessionService(db_url=config.DB_URL)
self._runner = Runner(app_name=config.APP, agent=wf, session_service=self._svc)

async for ev in self._runner.run_async(user_id=config.USER, session_id=run_id, new_message=message):
    self._absorb(ev)    # fold the ADK event into the run state, publish one app event

# the gate's answer and the render's delivery are the same call, with a function_response part
part = Part(function_response=FunctionResponse(id=call_id, name=name, response=response))
  • run_async: управляет выполнением рабочего процесса, последовательно генерируя события по мере выполнения узлов и сохраняя обновления в сервисе сеансов.
  • Единое возобновление. Решения пользователя в direction_gate и завершенные видео, созданные Veo, возобновляют выполнение с помощью идентичных объектов FunctionResponse, отправленных в run_async.

Архитектура рабочей версии приложения

В приложении для производства vibestudio/ реализован полный конвейер:

vibestudio/
  server/
    main.py                 FastAPI: application server, REST routes, static assets
    api.py                  REST API endpoints: run, pick, publish, backlog, profile, history
    runner.py               Runner orchestration over the workflow, background render poller
    platform/               Event bus (SSE stream), file storage, publishing, telemetry
    agent/                  Production agent package, verified by checks/verify_app.py
      graph.py              The complete workflow graph and node definitions
      desk.py               render_desk and render_submit wrapped with LongRunningFunctionTool
      schemas.py            Pydantic schemas: Directions, CleanedDirection, Script
      cleanup_tools.py      Deterministic policy tools: find_policy_hits, suggest_replacement
      platform/             Memory Bank, RAG Engine, and Veo integrations
  web/                      Production React user interface
  Dockerfile · deploy.py · run.sh
  • Поток одиночных событий. Серверная часть FastAPI публикует события в одном потоке Server-Sent Events (SSE). Интерфейс React визуализирует прогресс графа в реальном времени и обрабатывает поздние подключения без потери состояния.
  • Раздельное выполнение. Приложение управляет циклом событий. Граф рабочего процесса содержит только логику выполнения и не связан с интерфейсом.

Полный список ребер рабочего процесса в agent/graph.py объединяет все архитектурные шаблоны, созданные в ходе этой практической работы:

        (START, scan_trends, join_research),
        (START, read_backlog, join_research),
        (START, read_feedback, join_research),
        (join_research, propose_directions, direction_gate,
         persist_direction, policy_check),
        (policy_check, {"OK": scripter, "BLOCK": quarantine}),
        (quarantine, scripter),
        (scripter, render_desk, store_video),

Выполняем развертывание в Cloud Run…

Google Cloud Run предоставляет бессерверный хостинг с автомасштабированием, маршрутизацией запросов и интегрированными сборками контейнеров:

gcloud run deploy vibestudio --source vibestudio \
  --project $GOOGLE_CLOUD_PROJECT --region us-central1 \
  --labels dev-tutorial-codelab=vibetube --allow-unauthenticated \
  --memory 2Gi --cpu 2 --timeout 3600 --concurrency 40 \
  --max-instances 1 --min-instances 1 --session-affinity \
  --set-env-vars GOOGLE_CLOUD_PROJECT=...,STUDIO_VERTEX=1,STUDIO_MEMORY_BANK=...,STUDIO_RAG_CORPUS=...,VIBETUBE_URL=...,VIBETUBE_EVENT=...,VIBETUBE_NAME=...,VIBETUBE_PROJECT=...
  • Сборка контейнера. gcloud run deploy --source упаковывает каталог vibestudio/, создает образ контейнера с помощью Cloud Build и развертывает сервис за одну операцию.
  • Привязка сеанса. Направляет запросы от одного пользователя в один и тот же экземпляр контейнера, сохраняя состояние локального сеанса на протяжении итеративных шагов.
  • Наблюдаемость. Интеграция Cloud Trace записывает распределенные интервалы для каждого узла, вызова LLM и выполнения инструмента, доступные в консоли Google Cloud в разделе "Обозреватель трассировки".

Нажмите кнопку Развернуть на рабочей станции, чтобы выполнить скрипт развертывания. После завершения сборки в терминале появится URL сервиса.

Для приложений

10. Сводка

В VibeStudio Workbench перейдите к шагу 10 "Сводка", чтобы посмотреть готовую архитектуру.

10-summary

Шаг

Архитектура и концепции

Шаблон реализации

один запрос;

Один запрос, инструменты функций, последовательный цикл чата

Agent(tools=[...]), function_call / function_response

Основы агентных рабочих процессов

Рабочий процесс с графом, параллельное исследование, выходные данные схемы, проверка человеком

Workflow, START, JoinNode, output_schema, RequestInput

State и Router

Общее состояние сеанса, привязка параметров, детерминированная маршрутизация, агент задач

Event(state=...), Event(route=...), mode="task", finish_task

Memory Bank

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

memories.generate / retrieve, before_model_callback, after_agent_callback

RAG Engine

Извлечение документов на основе комментариев аудитории, семантических встраиваний

Узел rag.create_corpus, RagEmbeddingModelConfig, read_feedback

Асинхронное создание видео с помощью Veo

Длительно выполняющиеся инструменты, ожидающие подтверждения получения, внешний демон доставки

LongRunningFunctionTool, FunctionResponse(id=...) возобновление

Развернуть в Cloud Run

Программная оркестровка, события, отправляемые сервером, бессерверный контейнер

Runner(agent=wf), run_async, развертывание Cloud Run

Основные принципы архитектуры

  1. Приостановка вместо ожидания. Рабочие процессы приостанавливаются для ввода данных человеком (RequestInput) или выполнения продолжительных операций (LongRunningFunctionTool). Процессы не простаивают в ожидании потоков или сетевых сокетов.
  2. Универсальное возобновление. Каждая приостановка возобновляется с помощью одного и того же механизма: одного сообщения function_response с идентификатором вызова приостановленного узла.
  3. Раздельное управление состоянием. Узлы обмениваются данными с помощью именованных ключей состояния сеанса и привязки параметров, а не подробных промежуточных полезных нагрузок с жесткой связью.
  4. Детерминированная маршрутизация до генеративных затрат. Маршрутизаторы на основе правил и фильтры регулярных выражений оценивают правила с нулевой стоимостью токенов до запуска генеративных моделей.
  5. Разделение задач. Контекст, относящийся к отдельному агенту, должен находиться в обратных вызовах жизненного цикла, а общие зависимости данных –

10 вариантов