Посібник розробника щодо багатоагентних шаблонів з ADK

Головна » Python » Посібник розробника щодо багатоагентних шаблонів з ADK

Агентні додатки швидко переростають класичний шаблон «єдиного мега-запиту», і розробникам потрібна надійна ментальна модель для структурування кількох агентів без занурення в хаос. Комплект розробки агентів (ADK) від Google був розроблений саме для цього: він дозволяє вам створювати надійні багатоагентні системи, підключати інструменти та пам'ять, а також розгортати все в Google Cloud з оглядовістю, безпекою та контролем витрат на рівні виробничого процесу.

Цей посібник ознайомить вас з основними шаблонами мультиагентів, що підтримуються ADK – від простих ієрархій батьків/дочірніх об’єктів до послідовних, циклічних та паралельних агентів робочих процесів – і покаже, як вони вписуються в ширшу еталонну архітектуру Google Cloud. Ми також розглянемо стан спільного сеансу, механізми делегування, загальні багатоагентні схеми та практичні аспекти розгортання, захисту та експлуатації цих систем у реальних середовищах.

Чому в ADK потрібні багатоагентні системи?

Коли застосунок керується єдиним монолітним запитом агента, його швидко стає важко обмірковувати, тестувати та розвивати. Величезні запити крихкі, їх важко налагоджувати та обслуговувати, оскільки вимоги зростають. ADK підштовхує вас до створення Багатоагентна система (MAS) де кожен агент має сфокусовану відповідальність, а оркестрація є явною.

Структурування вашої програми як кількох взаємодіючих агентів забезпечує модульність, спеціалізацію та можливість повторного використання. Ви можете мати дослідницького агента, критика, файлового записувача, маршрутизатора, агента доступу до даних і повторно використовувати їх у різних проектах або робочих процесах, замість того, щоб повторно вбудовувати ту саму логіку в одне величезне запитування.

ADK надає вам конкретні будівельні блоки для реалізації цього: агенти, орієнтовані на LLM, агенти робочих процесів (послідовні, паралельні, циклічні) та користувацькі агенти, що інкапсулюють логіку, відмінну від LLM. Всі вони успадковують від спільного BaseAgent, тому вони підключаються до тієї ж моделі оркестрації, ведення журналу, обробки станів та системи інструментів.

У міру зростання систем ця композиційна модель масштабується краще, ніж спеціальний код оркестрації або глибоко вкладені ланцюжки викликів функцій навколо однієї моделі. Ви підтримуєте кероване когнітивне навантаження: кожен агент має чіткий мандат та чітко визначену поверхню взаємодії з іншими.

Примітиви ADK для створення агентів

ADK надає невеликий набір примітивів, які можна комбінувати для вираження напрочуд багатих багатоагентних архітектур. Розуміння цих основних концепцій значно полегшує міркування про закономірності вищого рівня пізніше.

Перший примітив – це ієрархія агентів: кожен агент може оголосити список sub_agents, утворюючи дерево з одним root_agent на вершині. Коли ви передаєте дітей у sub_agents, ADK автоматично переводить свої parent_agent посилання та забезпечує, щоб даний екземпляр мав лише одного батьківського об'єкта (інакше ValueError піднімається).

Ця ієрархія — це більше, ніж просто декор: вона визначає, яким агентам дозволено делегувати кому повноваження, і це область, яка використовується агентами робочого процесу та передачею, керованою LLM. Від будь-якого агента ви можете перейти вгору через agent.parent_agent або знайти нащадків з agent.find_agent(name), що надзвичайно зручно для налагодження.

Окрім базових агентів LLM, ADK представляє спеціалізовані агенти робочих процесів – SequentialAgent, ParallelAgent та LoopAgent – чия робота полягає не в тому, щоб «думати», а в тому, щоб керувати субагентами. Усі вони мають один і той самий інтерфейс, але реалізують різні стратегії виконання: запуск по порядку, паралельне розгортання або ітерація в циклі з явними правилами завершення.

Третім важливим примітивом є комунікаційний рівень, зосереджений на спільному Session і її state словник. Стан сеансу діє як звичайна біла дошка: будь-який агент або інструмент може записувати проміжні результати або прапорці, а інші агенти в тому ж виклику можуть їх читати, часто за допомогою шаблонів ключів у своїх інструкціях (наприклад {PLOT_OUTLINE?}).

Як агенти спілкуються один з одним в ADK

ADK підтримує три додаткові режими зв'язку між агентами: спільний стан сеансу, передача, керована LLM, та явний виклик через AgentTool. Вибір правильного варіанта для кожної взаємодії забезпечує одночасно виразність та передбачуваність вашої системи.

Стан спільного сеансу (session.state) є найпростішим і найпоширенішим механізмом. Під час одного виклику всі агенти бачать одне й те саме Session об'єкт через InvocationContextІнструмент або зворотний виклик може це зробити context.state = value, а пізніший агент може отримати його за допомогою context.state.get("data_key")Для агентів LLM, налаштування output_key автоматично зберігає свою остаточну відповідь під цим ключем.

Делегування, кероване LLM, яке іноді називають «передачею агента», дозволяє LLM вирішувати, коли передавати завдання іншому агенту на основі інструкцій та описів агентів. Внутрішньо модель викликає спеціальну функцію, таку як transfer_to_agent(agent_name="screenwriter"). ADK AutoFlow перехоплює цей виклик і перенаправляє виконання до вибраного агента в межах дозволеної області дії (батьківський, дочірній, братній/сестринський об'єкти, залежно від конфігурації).

Явний виклик за допомогою AgentTool надає вам більш контрольований, функціональний спосіб виклику одного агента з іншого. Ви обгортаєте екземпляр цільового агента в AgentTool, додайте його до абонента tools список, і LLM може вибрати цей інструмент, як і будь-яку іншу функцію. Під час виклику, AgentTool.run_async виконує субагент, об'єднує стан та артефакти назад і повертає відповідь субагента як результат роботи інструменту.

Ці три канали покривають більшість потреб багатоагентної взаємодії: асинхронна передача даних через стан, гнучка маршрутизація через передачу та чіткі синхронні виклики через інструменти. У складніших конструкціях їх часто змішують в одному дереві: маршрутизатор, який передає дані дочірнім елементам, спеціалісти, які використовують стан для зв'язку, та один або два агенти, доступні як інструменти для спеціального делегування.

Структурні блоки: агенти LLM, агенти робочих процесів та користувацькі агенти

Більшість топологій MAS в ADK є комбінаціями трьох типів агентів: агентів на основі LLM, агентів робочих процесів та користувацьких агентів. Кожна категорія вирішує різний аспект проблеми оркестрації.

Агенти LLM обгортають велику мовну модель та додаткові інструменти, зворотні виклики та маршрутизацію виводу в BaseAgent. Уявіть їх як ваші «мислячі» компоненти: вони інтерпретують введені користувачем дані, викликають інструменти, оновлюють стан та або відповідають користувачеві, або передають завдання іншому агенту.

Агенти робочого процесу діють як менеджери, а не як працівники: вони не міркують самі, але контролюють порядок, паралелізм та повторення виконання субагентів. SequentialAgent запускає своїх дітей одну за одною, одночасно ділячись одним і тим самим InvocationContext, ParallelAgent розходяться по кількох гілках, які мають спільний стан, але різні гілки історії, та LoopAgent виконує послідовність багаторазово, доки не буде виконано умову зупинки.

Розширення митних агентів BaseAgent з довільною логікою, відмінною від LLM, коли вбудованих стратегій оркестрації недостатньо. Наприклад, ви можете реалізувати власний планувальник, який умовно виконує агенти на основі метрик, або інтегрувати механізм бізнес-правил, який визначає, який підпотік запускати залежно від нормативних обмежень.

Таке поєднання універсальних примітивів оркестрації та підключаємої логіки робить ADK придатним для серйозних корпоративних навантажень, а не лише для демонстрацій. Ви можете почати зі стандартних агентів робочого процесу, і лише коли вимоги стають екзотичними, ви звертаєтесь до CustomAgent.

Стан сеансу та шаблони пам'яті

Стан сесії в ADK лежить в основі як короткочасної розмовної пам'яті, так і структурованих даних, що передаються між агентами. У кожній розмові використовується Session об'єкт, що містить історію повідомлень та змінний об'єкт state словник, доступний усім агентам у цьому виклику.

Запис у стан зазвичай виконується всередині інструментів або зворотних викликів, використовуючи ToolContext or CallbackContext об'єкт Наприклад, такий інструмент, як save_attractions_to_state(tool_context, attractions: List) можна об'єднати нові пам'ятки з тими, що вже зберігаються в розділі state, повертаючи просте повідомлення про стан агенту, поки ADK зберігає дельту станів у сеансі.

Зчитування зі стану стало ергономічним завдяки вбудованим в інструкції ключовим шаблонам. Коли інструкція містить {my_key?}, ADK введе state якщо він існує; знак питання робить його необов'язковим, щоб агент не зазнавав невдачі, коли ключ відсутній. Це критично важливо в робочих процесах, таких як «дослідження → написання → рецензування», де кожен крок зчитує те, що зберіг попередній крок.

Для розмовної пам'яті протягом черги ключова ідея полягає в повторному використанні одного й того ж Session для наступних повідомлень користувачів замість створення нового щоразу. Завдяки спільному сеансу агент бачить попередні ходу та може обробляти подальші запитання, виправлення та багатоетапне планування. Якщо ви випадково створюєте новий сеанс за хід, агент поводиться так, ніби має амнезію: він не може пов’язати подальші дії з попереднім контекстом.

Стан також відіграє велику роль у агентах робочого процесу, таких як LoopAgent, які покладаються на постійні ключі, такі як лічильники, списки зворотного зв'язку або прапорці, щоб вирішити, чи потрібні додаткові ітерації. Агент критика може додавати коментарі до CRITICAL_FEEDBACK на кожному проході, поки планувальник або уточнювач зчитує цей ключ для покращення плану в наступній ітерації.

SequentialAgent: лінійні робочі процеси, зроблені явними

SequentialAgent – це ваш шаблон, до якого ви маєте звернути увагу, коли у вас є низка кроків, які необхідно виконати у фіксованому порядку. Уявіть собі такі процеси, як «аналіз запиту → дослідження → чернетка → збереження у файлі» або «визначення пункту призначення → планування маршруту → бронювання перевезення».

В ADK, a SequentialAgent має список sub_agents і запускає їх один за одним, пропускаючи ті самі InvocationContext через весь ланцюг. Тому що Session та state спільними, ви можете налаштувати перший агент для збереження його результату під output_key="destination" і наступний агент прочитав це через {destination} в інструкції без будь-якого клейового коду.

Класичним прикладом є генератор тону фільму: кореневий агент привітання спілкується з користувачем, а потім вручну працює над SequentialAgent що вимагає спочатку дослідника, потім сценариста, а потім файлообмінника. Користувач бачить лише кінцевий результат, але графік подій в ADK Web показує внутрішнє дерево: greeter → film_concept_team → .

Порівняно з ручною оркестрацією з явним if/elif блоки та виклики функцій, SequentialAgent зберігає декларативний характер потоку керування та мінімізує шаблонні елементи. Ви оголошуєте послідовність один раз і розглядаєте її як єдиного викликаного агента у вашому раннері або інтерфейсі користувача, використовуючи стан сеансу для передачі даних між кроками.

Послідовні робочі процеси також добре поєднуються з іншими агентами робочих процесів: ви можете вбудувати цикл або паралельне розгалуження як один із кроків у довшому ланцюжку. Ось так будуються більш складні процеси, такі як «повторне дослідження якості сюжету, потім аналіз касових зборів та кастингу, а потім написання зведеного звіту».

LoopAgent: ітеративне уточнення та кімнати для авторів

LoopAgent розроблено для завдань, які потребують кількох проходів роботи, доки не буде досягнуто певного порогу якості. Замість єдиного підходу «згенеруй один раз і сподівайся на краще», ви можете запрограмувати процес пропозицій, критики та вдосконалення.

Типова конфігурація циклу включає таких агентів, як дослідник, генератор (наприклад, сценарист) та критик, які співпрацюють протягом кількох раундів. На кожній ітерації дослідник може оновлювати фонові факти, сценарист коригує план або конспект, а критик оцінює його відповідно до чітких рекомендацій, вирішуючи, чи потрібні подальші ітерації.

Цикли зупиняються за двох умов: досягнення max_iterations або субагент, який сигналізує про виконання роботи. ADK надає вбудований інструмент, такий як exit_loop на який критик може звернутися, коли план, ескіз або проект проходить внутрішній контрольний список. LoopAgent також поважає escalate=True прапор Event дії, що дає вам ще один спосіб вирватися раніше.

Постійний стан сеансу тут є ключовим: агенти зчитують ключі, такі як PLOT_OUTLINE, research or CRITICAL_FEEDBACK і писати покращені версії або додаткові коментарі до кожного проходу. Цей шаблон ефективно імітує «кімнату письменників», де фахівці проводять мозковий штурм, критикують та шліфують, поки хтось не оголосить роботу готовою.

Поєднуючись LoopAgent з SequentialAgent, ви можете розмістити весь ітераційний цикл як лише один крок у більшому наскрізному робочому процесі. Наприклад, writers_room (LoopAgent) може запуститися спочатку, щоб створити чіткий контур графіка, після чого file_writer Агент зберігає результат і додає інші звіти.

ParallelAgent: розгалуження та збір для незалежних завдань

ParallelAgent реалізує класичний шаблон «розгортання / збирання» для завдань, які є незалежними, але мають спільний контекст. Замість того, щоб виконувати N кроків дослідження послідовно, ви запускаєте їх усі одночасно та чекаєте, поки всі вони завершаться, а потім об'єднуєте їхні результати.

Внутрішньо, ParallelAgent надає кожному субагенту окремий InvocationContext.branch - подобається ParentBranch.ChildName – при цьому все ще поділяючи те саме session.state. Це означає, що всі вони можуть читати початковий контекст, наприклад PLOT_OUTLINE, але слід записувати виходи в різні ключі стану (наприклад box_office_report, casting_report), щоб уникнути конфліктів.

Типовим прикладом є «команда передпродакшну» для презентації фільму: один агент оцінює потенціал касових зборів на основі порівнянних фільмів, інший пропонує варіанти кастингу, і обидва процеси відбуваються паралельно. Наступний file_writer потім створює звіт, використовуючи ключові шаблони для кожного підрезультату, та зберігає його на диску.

Паралельні робочі процеси значно зменшують затримку для широких запитів та в різних сценаріях. аналіз даних у реальному часіЯкщо вам потрібні поради щодо музеїв, варіантів концертів та ресторанів на вихідні, паралельний запуск трьох спеціалізованих агентів буде швидшим, ніж послідовний запит до них. Після розпалювання агент синтезу зчитує всі результати зі стану та створює уніфіковану відповідь для користувача.

Паралельні кроки майже завжди вбудовані всередині SequentialAgent який спочатку готує контекст, а потім запускає ParallelAgent, а потім продовжується агрегація та звітність. Цей шаблон легко розпізнати та використовувати повторно, щойно ви освоїтеся з агентами робочих процесів ADK.

Шаблони оркестрації з примітивами ADK

Як тільки ви зрозумієте ієрархію, агентів робочого процесу та стан, ви зможете реалізувати кілька класичних багатоагентних шаблонів безпосередньо в ADK. Ці шаблони не є жорстко запрограмованими примітивами, а композиціями, побудованими з тих самих базових будівельних блоків.

Шаблон координатора/диспетчера використовує центральний агент LLM як «маршрутизатор» для запитів користувачів, підтриманий кількома спеціалізованими субагентами. Координатор читає запит, потім або передає керування субагенту через делегування, кероване LLM, або явно викликає спеціалістів, використовуючи AgentToolТиповими прикладами є агенти з харчування, транспорту або гідів вихідного дня.

Послідовний шаблон конвеєра — це просто SequentialAgent кожен з дочірніх елементів реалізує чітко визначений крок процесу. Потоки «генератор-критик» є класичним варіантом: перший агент пише чернетку та зберігає її під output_key, другий агент аналізує його та зберігає відгук, а можливо, третій агент уточнює результат на основі цього відгуку.

Паралельна схема розгалуження/збирання виражається як ParallelAgent вкладені в послідовний робочий процес. Паралельні дочірні процеси записують результати в окремі ключі станів; пізніший агент-синтезатор зчитує їх назад і представляє об'єднану відповідь.

Ієрархічна декомпозиція завдань природним чином виникає з дерева батьків/дочірніх об'єктів. Агенти вищого рівня розбивають цілі на підцілі та делегують їх дочірнім об'єктам (або за допомогою делегування, або інструментів), а результати повертаються вгору по дереву. Це особливо корисно для асистентів дослідників, оптимізаторів ланцюгів поставок або систем фінансових консультантів, де кожен піддомен має свого власного спеціалізованого агента.

Ітеративне уточнення за допомогою LoopAgent формалізує цикл генератор-критик у шаблон повторного використання. Цикл виконує агентів планувальника, критика та уточнювача кілька разів, використовуючи ключі стану для збереження останнього плану та відповідного зворотного зв'язку, зупиняючись, коли досягнуто критерію якості або обмеження ітерацій.

Еталонна архітектура для багатоагентних систем у Google Cloud

Окрім логіки агента, вам все ще потрібно десь запускати свою систему, і Google Cloud пропонує чітко визначену еталонну архітектуру для багатоагентних розгортань виробничого рівня. На загальному рівні, рішення поєднує фронтенд, середовища виконання агентів, моделі штучного інтелекту Vertex, служби безпеки та додаткові інструментальні фреймворки, такі як MCP.

Типова настройка починається з фронтенду – часто інтерфейсу чату – який працює на Cloud Run. Користувачі взаємодіють з цим інтерфейсом користувача, який пересилає запити агенту-координатору, що надається як сервіс. Потім цей координатор вибирає між різними робочими процесами агента на основі намірів користувача, включаючи додаткові шляхи «людина в циклі», де люди можуть перевіряти або змінювати рішення агента.

Самі агенти можуть працювати в кількох середовищах: хмарні сервіси, Google Kubernetes Engine (GKE) або Vertex AI Agent Engine. ADK охоплює ці опції, абстрагуючи деякі деталі середовища виконання, щоб розробник зосереджувався на логіці агента, а не на налагодженні інфраструктури.

Усі виклики агентів покладаються на Vertex AI або інші середовища виконання моделей для логічного висновку, часто обгорнуті Model Armor для очищення запитів та відповідей. Model Armor допомагає фільтрувати спроби впровадження запитів, витоки конфіденційних даних або шкідливий контент до або після викликів моделі, діючи як захисний бар'єр навколо генеративних компонентів.

Інструменти та сервери MCP (Model Context Protocol) з'являються, коли агенти повинні взаємодіяти із зовнішніми системами – базами даних, файловими системами або SaaS API – стандартизованим способом. MCP визначає спільний контракт між агентом та сервером інструментів, тому один клієнт MCP у вашому агенті може отримати доступ до багатьох інструментів, створених різними командами, без тісного зв'язку; це включає міркування про Системи зберігання даних y cómo exponerlos de forma segura.

Безпека та управління для агентних застосунків

Агентні системи створюють проблеми безпеки, які виходять за рамки традиційних мікросервісів, оскільки LLM можуть бути обманом змусити їх неправильно використовувати інструменти або витікати дані, якщо не бути обережним. Рекомендований підхід Google поєднує детерміновані засоби контролю безпеки з захисними механізмами, що враховують LLM та керуються політиками; також є ключовими моментами для розуміння. обмеження, сесії та ризики de los modelos al diseñar estas defensas.

Людський нагляд залишається першорядним: процеси з високим рівнем впливу повинні включати етапи затвердження, де людина може призупинити, переглянути або накласти вето на запропоновану агентом дію. Це можна змоделювати як спеціалізований інструмент «підтвердження людиною», який передає запити до інтерфейсу користувача та відновлює виконання лише після відповіді людини.

Контроль доступу для агентів здійснюється через IAM: кожен обліковий запис агента або служби повинен мати лише мінімальні дозволи, необхідні для виконання своїх обов'язків. Якщо певний агент скомпрометовано або використовується неналежним чином, радіус вибуху обмежений, оскільки його обліковий запис служби не може отримати доступ до непов'язаних ресурсів або інструментів.

Інструментальне управління на основі політик, реалізоване за допомогою таких компонентів, як SecurityPlugin плюс PolicyEngine, дозволяє вимагати підтвердження користувача перед запуском певних інструментів. Коли політика позначає конфіденційний виклик, плагін перехоплює його, викликає спеціальну функцію «запит на підтвердження» та очікує на результат від вашої програми, фактично залучаючи людину до операцій з високим рівнем ризику.

Стандартні функції безпеки Google Cloud доповнюють картину: VPC Service Controls для зменшення ризику витоку даних, CMEK для ключів шифрування, керованих клієнтами, Cloud Armor для захисту від WAF та DDoS, IAP або Identity Platform для автентифікації користувачів та детальна IAM для доступу до ресурсів. Для зв'язку між агентами через A2A у робочому середовищі потрібна або рекомендована автентифікація на основі TLS 1.2+ та OAuth.

Надійність, спостережуваність та оптимізація витрат

Розгортання MAS у виробничому середовищі повинні бути надійними, доступними для спостереження та економічно ефективними; ADK добре інтегрується з операційними інструментами Google Cloud, щоб зробити це можливим. Ви можете інструменталізувати агенти, сеанси та інструменти таким чином, щоб їхні журнали та трасування відображалися в Cloud Logging та Cloud Trace.

З точки зору надійності, розробіть граф агентів таким чином, щоб він толерував збої в окремих компонентах. По можливості уникайте єдиного, незамінного центрального мозку; дозвольте незалежним агентам виконувати локалізовані завдання, щоб збій в одному з каналів не призвів до збою всієї програми; також, технічні завдання, як balanceo de carga en búsqueda distribuida para distribuir carga y reducir puntos de fallo. Симулюйте невдачі в постановці, щоб підтвердити координаційну поведінку під стресом.

Для викликів моделей Vertex AI підтримує динамічні спільні квоти та виділену пропускну здатність. Спільні квоти дозволяють уникнути жорстких обмежень для кожного проекту в сценаріях оплати за використання, тоді як виділена пропускна здатність є важливою для робочих навантажень з високим QPS та чутливими до затримки, які не потрібно обмежувати. Моніторинг частоти запитів та використання токенів допомагає вам вирішити, коли переходити від надання послуг на вимогу до виділеної потужності.

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

Налаштування ресурсів Cloud Run та довгострокові знижки додатково оптимізують витрати на виконання. Почніть зі стандартного процесора/пам'яті, спостерігайте за реальним використанням та встановлюйте корективи. Для передбачуваних робочих навантажень знижки на гарантоване використання значно зменшують витрати.

З точки зору спостережуваності, у вашій стратегії моніторингу слід розглядати агентів як першокласні сутності. Реєструйте їхні вхідні дані, рішення (наприклад, які інструменти вони викликають, якому агенту вони делегують) та зміни стану. Використовуйте графіки подій ADK у веб-інтерфейсі для налагодження окремих сеансів, а також хмарне ведення журналу та користувацькі інформаційні панелі для відображення тенденцій для всього автопарку.

Якщо ці методи добре виконані, ви отримаєте прозоре уявлення про вашу MAS: ви зможете побачити, які агенти працюють повільно, які інструменти використовуються надмірно, де запити занадто довгі та де виникають цикли контролю якості, такі як LoopAgent повторювати більше, ніж очікувалося. Цей цикл зворотного зв'язку має вирішальне значення для точного налаштування як якості, так і вартості з часом.

Поєднуючи примітиви агентів ADK, шаблони робочих процесів та механізми станів з еталонною архітектурою, стеком безпеки та операційними інструментами Google Cloud, ви можете розробляти багатоагентні системи, які не лише розумні на папері, але й легко розгортаються, керовані та економічно вигідні у виробництві. Починаючи з простих батьківських/дочірніх агентів і переходячи до послідовної, циклічної та паралельної оркестрації, ви отримуєте інструментарій для перетворення агентних ідей на надійні, зручні в обслуговуванні додатки, які фактично забезпечують бізнес-цінність.