Ръководство за разработчици за многоагентни модели с ADK

Начало » Питон » Ръководство за разработчици за многоагентни модели с ADK

Агентните приложения бързо надрастват класическия модел на „единична мега-подкана“ и разработчиците се нуждаят от солиден ментален модел, за да структурират множество агенти, без да изпадат в хаос. Комплектът за разработка на агенти (ADK) на Google е проектиран именно за това: той ви позволява да съставяте надеждни многоагентни системи, да свързвате инструменти и памет и да внедрявате всичко в Google Cloud с наблюдаемост, сигурност и контрол на разходите на производствено ниво.

Това ръководство ви превежда през основните многоагентни модели, поддържани от ADK – от прости йерархии родител/дъщеря до последователни, циклични и паралелни агенти за работни процеси – и показва как те се вписват в по-широка референтна архитектура в Google Cloud. Ще разгледаме също така споделеното състояние на сесията, механизмите за делегиране, общите многоагентни схеми и практическите аспекти на внедряването, осигуряването и работата на тези системи в реални среди.

Защо многоагентни системи в ADK?

Когато едно приложение се управлява от един-единствен, монолитен агентски команден код, бързо става трудно да се разсъждава, тества и развива. Огромните подкани са крехки, трудни за дебъгване и болезнени за поддръжка с нарастването на изискванията. ADK ви подтиква към изграждането на Многоагентна система (MAS) където всеки агент има фокусирана отговорност и оркестрацията е експлицитна.

Структурирането на приложението ви като няколко взаимодействащи си агенти носи модулност, специализация и възможност за многократна употреба. Можете да имате изследователски агент, критик, файлов писател, рутер, агент за достъп до данни и да ги използвате повторно в различни проекти или работни потоци, вместо да вграждате една и съща логика отново в един голям подкаст.

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

С разрастването на системите, този композиционен модел се мащабира по-добре от ad-hoc оркестрационния код или дълбоко вложените вериги от извиквания на функции около един модел. Поддържате когнитивното натоварване управляемо: всеки агент има ясен мандат и добре дефинирана повърхност за взаимодействие с останалите.

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 изпълнява подагента, обединява състоянието и артефактите обратно и връща отговора на подагента като резултат от инструмента.

Тези три канала покриват повечето нужди на многоагентния режим: асинхронно предаване на данни чрез state, гъвкаво маршрутизиране чрез transfer и тесни синхронни повиквания чрез инструменти. В по-сложни проекти често ги смесвате в едно дърво: рутер, който прехвърля към деца, специалисти, които използват състоянието за комуникация, и един или два агента, достъпни като инструменти за ad-hoc делегиране.

Градивни елементи: 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 поддържа декларативния контрол на потока и минимизира шаблонния код. Декларирате последователността веднъж и я третирате като единичен извикаем агент във вашия runner или UI, като същевременно използвате състоянието на сесията, за да предавате данни между стъпките.

Последователните работни потоци също се комбинират добре с други агенти на работни потоци: можете да вградите цикъл или паралелно разклонение като една от стъпките в по-дълга верига. Ето как се изграждат по-сложни потоци като „повтаряне на качеството на историята, след това анализ на боксофиса и кастинга, накрая писане на консолидиран отчет“.

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 предлага добре дефинирана референтна архитектура за многоагентни внедрявания от производствено ниво. На високо ниво, решението комбинира frontend, агентски runtime-ове, Vertex AI модели, услуги за сигурност и опционални инструменти като MCP.

Типичната настройка започва с интерфейс – често чат интерфейс – работещ на Cloud Run. Потребителите общуват с този потребителски интерфейс, който препраща заявки към координатор-агент, предоставен като услуга. След това координаторът избира между различни работни процеси на агентите въз основа на намерението на потребителя, включително опционални пътища „човек в цикъла“, където хората могат да валидират или отменят решенията на агентите.

Самите агенти могат да работят в няколко среди: Cloud Run services, Google Kubernetes Engine (GKE) или Vertex AI Agent Engine. ADK обхваща тези опции, абстрахирайки някои от детайлите по време на изпълнение, така че разработчикът да се фокусира върху логиката на агента, а не върху инфраструктурните тръбопроводи.

Всички повиквания към агенти разчитат на Vertex AI или други модели за изпълнение за извод, често обвити с Model Armor за дезинфекция на подканите и отговорите. Model Armor помага за филтриране на опити за инжектиране на prompts, изтичане на чувствителни данни или вредно съдържание преди или след извиквания на модел, действайки като предпазна преграда около генеративните компоненти.

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 в уеб потребителския интерфейс за отстраняване на грешки в отделни сесии и Cloud Logging плюс персонализирани табла за управление за тенденции в целия автопарк.

Ако се направят добре, тези практики ви дават прозрачен поглед върху вашата MAS: можете да видите кои агенти са бавни, кои инструменти се използват прекомерно, къде подканите са твърде дълги и къде са нарушени циклите за контрол на качеството, като например... LoopAgent итерирам повече от очакваното. Тази обратна връзка е от решаващо значение за финото настройване както на качеството, така и на разходите с течение на времето.

Чрез комбиниране на примитивите на агентите, моделите на работни процеси и механизмите за състояние на ADK с референтната архитектура, стека за сигурност и оперативните инструменти на Google Cloud, можете да проектирате многоагентни системи, които са не само интелигентни на хартия, но и лесно разгръщаеми, управляеми и икономически жизнеспособни в производство. Започвайки от прости родителски/дъщерни агенти и преминавайки през последователни, циклични и паралелни оркестрации, вие получавате набор от инструменти за превръщане на агентните идеи в надеждни, поддържаеми приложения, които действително предоставят бизнес стойност.