Google розклав ADK-агентів на три шари

Horizon у core/: піднімаєш локально, деплоїш командою make

Horizon — референсний харнес для агентів, що тримають контекст днями, а не один чат. Лежить у core/python/long-horizon-harness і зводить разом крос-сесійну пам'ять, пісочницю на кожного користувача, керування секретами, guardrails проти рантвей-поведінки та примітиви оркестрації для відновлюваних багатокрокових задач.

Шлях від клону до робочого інстансу:

• uvx google-agents-cli setup
• gcloud auth application-default login
• gcloud config set project YOUR_PROJECT_ID
• gcloud services enable aiplatform.googleapis.com
• git clone --depth 1 --filter=blob:none --sparse https://github.com/google/adk-recipes.git
• git sparse-checkout set core/python/long-horizon-harness
• make dev-local — за замовчуванням LHA_ENVIRONMENT_BACKEND=local, сесії в памʼяті, без хмарних деплоїв

make deploy розкочує бекенд на Cloud Run через Terraform, make destroy знімає. Якість перевіряється не вручну: у tests/eval/evalsets/ лежать 18 поведінкових рубрик — відтворення пам'яті, спроби exfiltration через інʼєкції, зупинка guardrails під адверсаріальним вводом, дисципліна вибору тулів і сюжетна оцінка на рівні цілого journey. Запускаються командою uv run pytest tests/eval.

plugins/: встановлення retail-скіла одним рядком, але з нюансом у флагу

Плагіни ставляться командою npx skills add google/adk-recipes --skill retail-product-search --full-depth. Флаг --full-depth критичний: за замовчуванням CLI шукає скіли лише на верхньому рівні репозиторію, а retail-скіли лежать глибше, у plugins/retail/skills/. Без флага CLI їх просто не знайде.

Встановлене лягає в ~/.agents/skills/<skill-name>/ і симлінкається у кожен виявлений на машині асистент. Далі асистент читає SKILL.md і запускає розмовний інсталятор: Quick Start — це два питання (ID GCP-проєкту і шлях до даних про товари, з дефолтами на обидва), Full Setup додає ще два — рівень деталізації полів товару і регіон GCP.

За результатами інтервʼю скіл пише ./design-spec.md і виконує scripts/setup.py: заливає каталог у BigQuery, генерує ембединги через Vertex AI Embeddings, будує колекцію Vector Search і прогонятиме EVAL.yaml. Якщо рубрики й детерміновані перевірки не набирають порогу 80%, скіл зупиняється і показує, що саме провалилось — тобто результат не можна просто прийняти на віру, бо він сам сигналізує про провал.

retail-product-search додатково тягне супутні скіли з google/skills (базові речі про BigQuery і Gemini API), якщо їх ще немає — це розрахунок на композицію скілів, а не на монолітний пакет.

contrib/: від скіла до сервісу, що реально деплоїться

У contrib/ сьогодні 12 Python-агентів — фінанси (фінансовий консультант, обробник кредитів для малого бізнесу), оцінка (LLM-аудитор), документи й знання (аналізатор великих обсягів документів, гібридний RAG), контент і бренд, retail (product-search, virtual-tryon) та навчальні приклади по агентним скілам. Java, Go, TypeScript і Kotlin мають менші набори.

Плагін і contrib-агент підтримує одна команда, щоб вони не розходились. README агента прямо каже спершу прогнати сетап плагіна: make -C plugins/retail/skills/product-search setup PROJECT_ID=your-project. Коли колекція retail-skill-products-collection заповнена, агент деплоїться в одній із пʼяти конфігурацій, які перемикаються булевими флагами в .env.

product-search свідомо зроблений однoагентним — один root_agent з одним тулом ретрівалу, без координаційного шару. Складність винесена в пайплайн ретрівалу й рубрику оцінки, а не в комунікацію між агентами: автори вважають, що оркестраційні шари тут радше заплутали б картину, ніж прояснили.

Де прийом не працює і що перевірити перед деплоєм

Репозиторій прямо позначений як неофіційний продукт Google: рецепти — для демонстрації і як стартові точки, не для продакшена без доопрацювання. Інсталятор CLI при встановленні теж попереджає: скіли варто переглянути перед використанням, бо вони виконуються з повними правами агента.

• Забули --full-depth для вкладених плагінів — CLI мовчки не знаходить скіл, хоча він у репозиторії є.
• Прийняли прохід setup.py без помилок за успіх — дивитись треба саме на прохід порогу 80% в EVAL.yaml, а не на відсутність exceptions.
• Деплоять virtual-tryon без уваги до pre-flight класифікатора product-cutout і рівнів безпеки — за словами авторів, ці деталі «стають очевидними лише після третього реального продакшн-деплою».

AGENTS.md і manifest.yaml написані для асистента, а не для людини — перед використанням скіла читайте README.md, а не ці файли. Даних про дату запуску й ціну використання інфраструктури (Vector Search, Veo) у матеріалі немає.