Udviklervejledning til multiagentmønstre med ADK

Hjem » Python » Udviklervejledning til multiagentmønstre med ADK

Agentapplikationer vokser hurtigt fra det klassiske "single mega-prompt"-mønster, og udviklere har brug for en solid mental model til at strukturere flere agenter uden at de havner i kaos. Googles Agent Development Kit (ADK) blev designet netop til dette: det giver dig mulighed for at sammensætte pålidelige multiagentsystemer, integrere værktøjer og hukommelse og implementere alt på Google Cloud med observerbarhed, sikkerhed og omkostningskontrol i produktionsklassen.

Denne guide gennemgår de vigtigste multiagentmønstre, der understøttes af ADK – fra simple overordnede/underordnede hierarkier til sekventielle, løkke- og parallelle workflowagenter – og viser, hvordan de passer ind i en bredere referencearkitektur på Google Cloud. Vi vil også dække delt sessionstilstand, delegeringsmekanismer, fælles multi-agent blueprints og de praktiske aspekter ved implementering, sikring og drift af disse systemer i virkelige miljøer.

Hvorfor multiagentsystemer i ADK?

Når en applikation drives af en enkelt, monolitisk agentprompt, bliver det hurtigt svært at ræsonnere, teste og udvikle. Store prompts er skrøbelige, vanskelige at fejlfinde og smertefulde at vedligeholde, efterhånden som kravene vokser. ADK skubber dig i retning af at opbygge en Multiagentsystem (MAS) hvor hver agent har et fokuseret ansvar, og orkestrering er eksplicit.

At strukturere din app med flere samarbejdende agenter bringer modularitet, specialisering og genbrugelighed. Du kan have en forskningsagent, en kritiker, en filskriver, en router, en dataadgangsagent og genbruge dem på tværs af projekter eller arbejdsgange i stedet for at genindlejre den samme logik i én jumbo-prompt.

ADK giver dig konkrete byggesten til at realisere dette: LLM-centrerede agenter, workflow-agenter (sekventiel, parallel, loop) og brugerdefinerede agenter, der indkapsler ikke-LLM-logik. Alle arver fra en fælles BaseAgent, så de tilsluttes den samme orkestreringsmodel, logføring, tilstandshåndtering og værktøjssystem.

Efterhånden som systemerne vokser, skalerer denne kompositionsmodel bedre end ad hoc-orkestreringskode eller dybt indlejrede kæder af funktionskald omkring en enkelt model. Du holder den kognitive belastning håndterbar: hver agent har et klart mandat og en veldefineret interaktionsflade med andre.

ADK-primitiver til komponerende agenter

ADK eksponerer et lille sæt primitiver, som du kan kombinere for at udtrykke overraskende rige multi-agent-arkitekturer. At forstå disse kernebegreber gør det meget nemmere at ræsonnere om mønstre på højere niveau senere.

Den første primitive er agenthierarkiet: enhver agent kan deklarere en liste over sub_agents, der danner et træ med en enkelt root_agent på toppen. Når du afleverer børn i sub_agents, ADK forbinder automatisk deres parent_agent reference og håndhæver, at en given instans kun har én forælder (ellers en ValueError er hævet).

Dette hierarki er mere end blot dekoration: det definerer, hvilke agenter der har tilladelse til at delegere til hvilke, og det er det omfang, der bruges af workflow-agenter og LLM-drevet overførsel. Fra enhver agent kan du bevæge dig opad via agent.parent_agent eller find efterkommere med agent.find_agent(name), hvilket er yderst praktisk til debugging.

Ud over basale LLM-agenter introducerer ADK dedikerede workflow-agenter – SequentialAgent, ParallelAgent og LoopAgent – hvis opgave ikke er at "tænke", men at orkestrere underagenter. De deler alle den samme grænseflade, men implementerer forskellige udførelsesstrategier: kører i rækkefølge, udfolder sig parallelt eller itererer i en løkke med eksplicitte afslutningsregler.

Det tredje essentielle primitive lag er kommunikationslaget, centreret omkring det delte Session og state ordbog. Sessionstilstanden fungerer som en almindelig whiteboard: enhver agent eller et værktøj kan skrive mellemresultater eller flag, og andre agenter i samme kald kan læse dem, ofte via nøgleskabeloner i deres instruktioner (for eksempel {PLOT_OUTLINE?}).

Hvordan agenter taler med hinanden i ADK

ADK understøtter tre komplementære kommunikationstilstande mellem agenter: delt sessionstilstand, LLM-drevet overførsel og eksplicit kald via AgentTool. At vælge den rigtige til hver interaktion holder dit system både udtryksfuldt og forudsigeligt.

Delt sessionsstatus (session.state) er den enkleste og mest udbredte mekanisme. Inden for en enkelt kald ser alle agenter det samme Session objektet via InvocationContextEt værktøj eller et tilbagekald kan gøre context.state = value, og en senere agent kan hente den med context.state.get("data_key")For LLM-agenter, indstilling output_key bevarer automatisk deres endelige svar under den pågældende nøgle.

LLM-drevet delegering, undertiden kaldet "agentoverførsel", lader en LLM beslutte, hvornår der skal overdrages til en anden agent baseret på instruktioner og agentbeskrivelser. Internt udfører modellen et særligt funktionskald som f.eks. transfer_to_agent(agent_name="screenwriter")ADK'er AutoFlow opfanger dette kald og omdirigerer udførelsen til den valgte agent inden for det tilladte omfang (forælder, underordnede, søskende afhængigt af konfigurationen).

Eksplicit påkaldelse med AgentTool giver dig en mere kontrolleret, funktionslignende måde at ringe til én agent fra en anden. Du pakker en target agent-instans ind AgentTool, tilføj den til opkalderens tools liste, og LLM'en kan derefter vælge det værktøj som enhver anden funktion. Når den kaldes, AgentTool.run_async udfører underagenten, fletter tilstand og artefakter tilbage og returnerer underagentens svar som værktøjsresultatet.

Disse tre kanaler dækker de fleste behov for flere agenter: asynkron dataoverførsel via tilstand, fleksibel routing via overførsel og tætte synkrone kald via værktøjer. I mere komplekse designs blander man dem ofte i et enkelt træ: en router, der overfører til underordnede systemer, specialister, der bruger tilstand til at kommunikere, og en eller to agenter, der er tilgængelige som værktøjer til ad hoc-delegering.

Byggesten: LLM-agenter, workflow-agenter og brugerdefinerede agenter

De fleste MAS-topologier i ADK er kombinationer af tre agenttyper: LLM-baserede, workflow- og brugerdefinerede agenter. Hver kategori løser en forskellig del af orkestreringsproblemet.

LLM-agenter pakker en stor sprogmodel og valgfrie værktøjer, callbacks og outputrouting ind i BaseAgent. Tænk på dem som dine "tænkende" komponenter: de fortolker brugerinput, kalder værktøjer, opdaterer status og enten svarer brugeren eller videregiver til en anden agent.

Workflow-agenter fungerer som ledere snarere end arbejdere: de ræsonnerer ikke selv, men de kontrollerer rækkefølgen, parallelismen og gentagelsen af ​​underagenters udførelse. SequentialAgent kører sine børn efter hinanden, mens de deler det samme InvocationContext, ParallelAgent spreder sig over flere grene, der deler stat, men har forskellige historiske grene, og LoopAgent udfører en sekvens gentagne gange, indtil en stopbetingelse er opfyldt.

Brugerdefinerede agenter forlænger BaseAgent med vilkårlig ikke-LLM-logik, når de indbyggede orkestreringsstrategier ikke er tilstrækkelige. For eksempel kan du implementere en brugerdefineret planlægger, der udfører agenter betinget baseret på metrikker, eller integrere en forretningsregelmotor, der bestemmer, hvilket underflow der skal køres, afhængigt af lovgivningsmæssige begrænsninger.

Denne blanding af generiske orkestreringsprimitiver og pluggbar logik er det, der gør ADK velegnet til seriøse virksomhedsarbejdsbelastninger, ikke kun demoer. Du kan starte med standard workflow-agenterne, og først når kravene bliver eksotiske, griber du fat i dem CustomAgent.

Sessionstilstand og hukommelsesmønstre

Sessionstilstand i ADK understøtter både korttidshukommelse i samtale og overførsel af strukturerede data mellem agenter. Enhver samtale bruger en Session objekt, der indeholder beskedhistorik og en foranderlig state ordbog tilgængelig for alle agenter i den pågældende kald.

Skrivning til tilstand udføres normalt inde i værktøjer eller callbacks ved hjælp af ToolContext or CallbackContext objekt. For eksempel et værktøj som save_attractions_to_state(tool_context, attractions: List) kan flette nye attraktioner med dem, der allerede er gemt under state, der returnerer en simpel statusmeddelelse til agenten, mens ADK bevarer tilstandsdeltaet i sessionen.

Aflæsning fra tilstand gøres ergonomisk via nøgleskabeloner indlejret i instruktioner. Når en instruktion indeholder {my_key?}, ADK vil injicere state Hvis det findes, gør spørgsmålstegnet det valgfrit, så agenten ikke fejler, når nøglen mangler. Dette er afgørende i arbejdsgange som "research → write → review", hvor hvert trin læser, hvad det forrige trin gemte.

For samtalehukommelse på tværs af ture er hovedideen at genbruge den samme Session til efterfølgende brugerbeskeder i stedet for at oprette en ny hver gang. Med en delt session ser agenten tidligere ture og kan håndtere opfølgende spørgsmål, rettelser og flertrinsplanlægning. Hvis du ved et uheld opretter en helt ny session pr. tur, opfører agenten sig, som om den havde hukommelsestab: den kan ikke forbinde opfølgninger til tidligere kontekst.

Staten spiller også en stor rolle i arbejdsgangsagenter som f.eks. LoopAgent, som er afhængige af persistente nøgler såsom tællere, feedbacklister eller flag for at afgøre, om flere iterationer er nødvendige. En kritiker kan tilføje kommentarer til CRITICAL_FEEDBACK på hver gennemgang, mens en planlægger eller raffinør læser den nøgle for at forbedre planen i den næste iteration.

SequentialAgent: lineære arbejdsgange gjort eksplicitte

SequentialAgent er dit foretrukne mønster, når du har en række trin, der skal udføres i en fast rækkefølge. Tænk på pipelines som "analyser anmodning → research → kladde → gem til fil" eller "identificer destination → planlæg rute → book transport".

I ADK, en SequentialAgent indeholder en liste over sub_agents og kører dem en efter en, forbi den samme InvocationContext gennem hele kæden. Fordi Session og state deles, kan du få den første agent til at gemme sit resultat under output_key="destination" og den næste agent læste det via {destination} i sin instruktion uden nogen limkode.

Et klassisk eksempel er en film pitch generator: en greeter root agent taler til brugeren, og derefter arbejder hænderne med en SequentialAgent der kalder en forsker, derefter en manuskriptforfatter og derefter en filforfatter. Brugeren ser kun det endelige resultat, men hændelsesgrafen i ADK Web afslører det interne træ: greeter → film_concept_team → .

Sammenlignet med manuel orkestrering med eksplicit if/elif blokke og funktionskald, SequentialAgent holder kontrolflowet deklarativt og minimerer standardteksten. Du deklarerer sekvensen én gang og behandler den som en enkelt kaldbar agent i din runner eller brugergrænseflade, mens du udnytter sessionstilstanden til at overføre data mellem trin.

Sekventielle arbejdsgange kombineres også fint med andre arbejdsgangsagenter: du kan integrere et loop eller en parallel fan-out som et af trinnene i en længere kæde. Sådan opbygges mere avancerede flows som "iterér på historiekvalitet, kør derefter box-office- og castinganalyse, og skriv derefter en samlet rapport".

LoopAgent: iterativ forfining og skriverum

LoopAgent er designet til opgaver, der har gavn af flere gennemløb, indtil en kvalitetstærskel er nået. I stedet for en enkelt "generer én gang og håb på det bedste"-tilgang, kan du indkode en proces med forslag, kritik og forfinelse.

En typisk loopkonfiguration inkluderer agenter som en forsker, en generator (f.eks. manuskriptforfatter) og en kritiker, der samarbejder over flere runder. Ved hver iteration kan forskeren opdatere baggrundsfakta, manuskriptforfatteren justerer dispositionen eller planen, og kritikeren evaluerer den i forhold til eksplicitte retningslinjer og afgør, om flere iterationer er berettigede.

Løkker stopper under to betingelser: når max_iterations eller en underagent, der signalerer, at arbejdet er udført. ADK eksponerer et indbygget værktøj som f.eks. exit_loop som kritikeren kan ringe til, når en plan, disposition eller design består sin interne tjekliste. LoopAgent respekterer også en escalate=True flag ind Event handlinger, hvilket giver dig en anden måde at bryde ud tidligt.

Vedvarende sessionstilstand er nøglen her: agenter læser nøgler som PLOT_OUTLINE, research or CRITICAL_FEEDBACK og skriv forbedrede versioner eller yderligere kommentarer til hver gennemgang. Dette mønster simulerer effektivt et "forfatterrum", hvor specialister brainstormer, kritiserer og finpudser, indtil nogen erklærer værket for færdigt.

Ved at kombinere LoopAgent med SequentialAgent, kan du placere hele den iterative løkke som blot ét trin i en større end-to-end-arbejdsgang. For eksempel: writers_room (LoopAgent) kører muligvis først for at producere en solid plotoversigt, hvorefter en file_writer Agenten gemmer resultatet og vedhæfter andre rapporter.

ParallelAgent: udfold og saml til uafhængige opgaver

ParallelAgent implementerer det klassiske "fan-out / gather"-mønster for opgaver, der er uafhængige, men deler kontekst. I stedet for at køre N forskningstrin i serie, kører du dem alle på én gang og venter på, at alle er færdige, hvorefter du aggregerer deres output.

Internt, ParallelAgent giver hver underagent en distinkt InvocationContext.branch - synes godt om ParentBranch.ChildName – mens man stadig deler det samme session.state. Det betyder, at de alle kan læse den indledende kontekst, som f.eks. PLOT_OUTLINE, men bør skrive output til forskellige tilstandsnøgler (for eksempel box_office_report, casting_report) for at undgå konflikter.

Et almindeligt eksempel er et "forproduktionsteam" til en filmpitch: én agent vurderer box-office-potentialet baseret på sammenlignelige film, en anden foreslår castingmuligheder, der begge kører parallelt. En efterfølgende file_writer udarbejder derefter en rapport ved hjælp af nøgleskabeloner for hvert delresultat og gemmer den på disken.

Parallelle arbejdsgange reducerer latenstid betydeligt for brede forespørgsler og i særlige scenarier dataanalyse i realtidHvis du har brug for museumsforslag, koncertmuligheder og restaurantidéer til en weekend, er det hurtigere at køre tre specialistagenter parallelt end at forespørge dem sekventielt. Efter fan-out'en læser en synteseagent alle resultater fra state og producerer et samlet svar til brugeren.

Parallelle trin er næsten altid indlejret i en SequentialAgent der først forbereder kontekst og derefter kører ParallelAgent, fortsætter derefter med aggregering og rapportering. Dette mønster er nemt at genkende og genbruge, når du først er blevet fortrolig med ADKs arbejdsgangsagenter.

Orkestreringsmønstre med ADK-primitiver

Når du har forstået hierarki, workflow-agenter og tilstand, kan du implementere adskillige klassiske multi-agent-mønstre direkte i ADK. Disse mønstre er ikke hardkodede primitiver, men kompositioner bygget med de samme grundlæggende byggesten.

Koordinator/dispatcher-mønsteret bruger en central LLM-agent som en "router" til brugerforespørgsler, bakket op af flere specialiserede underagenter. Koordinatoren læser anmodningen og overfører derefter enten kontrollen til en underagent via LLM-drevet delegering eller ringer eksplicit til specialister ved hjælp af AgentToolMad-, transport- eller weekendguideagenter er almindelige eksempler.

Det sekventielle pipelinemønster er simpelthen et SequentialAgent hvis underordnede hver implementerer et velafgrænset trin i en proces. Generator-og-kritiker-flows er en klassisk variant: den første agent skriver et udkast og gemmer det under en output_key, den anden agent analyserer det og gemmer feedback, og måske forfiner en tredje agent resultatet baseret på denne feedback.

Det parallelle fan-out/samlemønster udtrykkes som et ParallelAgent indlejret i en sekventiel arbejdsgang. Parallelle børn skriver resultater i separate tilstandsnøgler; en senere synth-agent læser dem tilbage og præsenterer et kombineret svar.

Hierarkisk opgavenedbrydning opstår naturligt fra overordnede/underordnede-træet. Agenter på højere niveau opdeler mål i delmål og delegerer dem til undermål (enten via delegation eller værktøjer), hvor resultaterne rulles tilbage op i træet. Dette er især nyttigt i forskningsassistenter, forsyningskædeoptimerere eller finansielle rådgivningssystemer, hvor hvert underdomæne har sin egen specialistagent.

Iterativ forfining med LoopAgent formaliserer generator-kritiker-løkken til et genanvendeligt mønster. Løkken udfører planlægger-, kritiker- og forfineragenter flere gange ved hjælp af tilstandsnøgler til at bevare den seneste plan og tilsvarende feedback og stopper, når et kvalitetskriterium eller en iterationsgrænse er nået.

Referencearkitektur for multiagentsystemer på Google Cloud

Ud over agentlogik skal du stadig køre dit system et sted, og Google Cloud tilbyder en veldefineret referencearkitektur til multi-agent-implementeringer i produktionsklassen. På et overordnet niveau kombinerer løsningen en frontend, agent runtime, Vertex AI-modeller, sikkerhedstjenester og valgfrie værktøjsframeworks som MCP.

Den typiske opsætning starter med en frontend – ofte en chatgrænseflade – der kører på Cloud Run. Brugere kommunikerer med denne brugergrænseflade, som videresender anmodninger til en koordinatoragent, der er eksponeret som en tjeneste. Denne koordinator vælger derefter mellem forskellige agentarbejdsgange baseret på brugerens intention, herunder valgfrie human-in-the-loop-stier, hvor folk kan validere eller tilsidesætte agentbeslutninger.

Agenter kan selv køre i flere miljøer: Cloud Run-tjenester, Google Kubernetes Engine (GKE) eller Vertex AI Agent Engine. ADK spænder over disse muligheder og abstraherer nogle af runtime-detaljerne, så udvikleren fokuserer på agentlogik snarere end infrastrukturens VVS.

Alle agentkald er afhængige af Vertex AI eller andre modelkørselstider til inferens, ofte pakket ind i Model Armor for at rense prompts og svar. Model Armor hjælper med at filtrere forsøg på hurtig indsprøjtning, lækager af følsomme data eller skadeligt indhold før eller efter modelkald og fungerer som et sikkerhedsgelænder omkring generative komponenter.

MCP-værktøjer (Model Context Protocol) og -servere kommer i billedet, når agenter skal kommunikere med eksterne systemer – databaser, filsystemer eller SaaS API'er – på en standardiseret måde. MCP definerer en fælles kontrakt mellem agent og værktøjsserver, så en enkelt MCP-klient i din agent kan få adgang til mange værktøjer bygget af forskellige teams uden tæt kobling; dette inkluderer overvejelser om datalagringssystemer y como exponerlos de forma segura.

Sikkerhed og styring for agentapplikationer

Agentiske systemer introducerer sikkerhedsudfordringer, der går ud over traditionelle mikrotjenester, fordi LLM'er kan blive narret til at misbruge værktøjer eller lække data, hvis man ikke er forsigtig. Googles anbefalede tilgang kombinerer deterministiske sikkerhedskontroller med LLM-bevidste, politikdrevne forsvar; det er også nøglen til at forstå dem grænser, sesgos og risgos de los modelos al diseñar estas defensas.

Menneskeligt tilsyn er fortsat altafgørende: flows med stor indflydelse bør omfatte godkendelsestrin, hvor en person kan sætte en agents foreslåede handling på pause, gennemgå eller nedlægge veto mod den. Dette kan modelleres som et dedikeret "menneskelig bekræftelses"-værktøj, der viser anmodninger til en brugergrænseflade og først genoptager udførelsen, når et menneske svarer.

Adgangskontrol for agenter håndteres via IAM: hver agent eller servicekonto bør kun have de minimale tilladelser, der kræves for at udføre sine opgaver. Hvis en given agent kompromitteres eller misbruges, er eksplosionsradiusen begrænset, fordi dens servicekonto ikke kan få adgang til ikke-relaterede ressourcer eller værktøjer.

Politikdrevet værktøjsstyring, implementeret med komponenter som en SecurityPlugin plus en PolicyEngine, giver dig mulighed for at kræve brugerbekræftelse, før bestemte værktøjer kører. Når en politik markerer et følsomt kald, opfanger plugin'et det, udsender et særligt "bed om bekræftelse"-funktionskald og venter på, at din applikation returnerer en dom, hvilket effektivt sætter et menneske i loopet for højrisikooperationer.

Standard Google Cloud-sikkerhedsfunktioner fuldender billedet: VPC-servicekontroller reducerer risikoen for dataeksfiltrering, CMEK til kundeadministrerede krypteringsnøgler, Cloud Armor til WAF- og DDoS-beskyttelse, IAP eller Identity Platform til brugergodkendelse og detaljeret IAM til ressourceadgang. Til agent-til-agent-kommunikation via A2A kræves eller anbefales TLS 1.2+ og OAuth-baseret godkendelse i produktion.

Pålidelighed, observerbarhed og omkostningsoptimering

Produktions-MAS-implementeringer skal være pålidelige, observerbare og omkostningseffektive; ADK integrerer godt med Google Clouds driftsværktøjer for at gøre dette muligt. Du kan instrumentere agenter, sessioner og værktøjer, så deres logfiler og spor vises i Cloud Logging og Cloud Trace.

Fra et pålidelighedssynspunkt skal du designe din agentgraf til at tolerere fejl i individuelle komponenter. Hvor det er muligt, undgå en enkelt, uerstattelig central hjerne; lad uafhængige agenter udføre lokaliserede opgaver, så et nedbrud i én sti ikke bringer hele applikationen ned; además, emplea tecnicas como balanceo de carga en búsqueda distribution para distribuir carga y reducir puntos de fallo. Simuler fejl i iscenesættelsen for at validere koordinationsadfærd under stress.

For modelkald understøtter Vertex AI dynamiske delte kvoter og provisioneret gennemløb. Delte kvoter undgår hårde grænser pr. projekt i pay-as-you-go-scenarier, mens provisioneret gennemløb er afgørende for arbejdsbelastninger med høj QPS og latenstid, der ikke må begrænses. Overvågning af anmodningsrater og tokenbrug hjælper dig med at beslutte, hvornår du skal skifte fra on-demand til provisioneret kapacitet.

Omkostningskontrol afhænger i høj grad af smart modelvalg, omhyggeligt og hurtigt design og undgåelse af unødvendige tokens. Start med omkostningseffektive modeller, hvor du kan, hold prompterne præcise, men informative, bed eksplicit om korte output, når det er muligt, udnyt kontekstcaching til gentagne store prompter, og overvej batchforudsigelser, når arbejdsbelastninger tillader det.

Cloud Run-ressourcejustering og langsigtede rabatter optimerer yderligere runtime-omkostningerne. Start med standard CPU/hukommelse, observer det faktiske forbrug og juster. For forudsigelige arbejdsbelastninger reducerer rabatter på committed use udgifterne betydeligt.

På observerbarhedssiden bør du behandle agenter som førsteklasses enheder i din overvågningsstrategi. Log deres input, beslutninger (f.eks. hvilke værktøjer de ringer til, hvilken agent de delegerer til) og statusændringer. Brug ADK's hændelsesgrafer i webgrænsefladen til fejlfinding af individuelle sessioner og Cloud Logging plus brugerdefinerede dashboards til flådeomfattende tendenser.

Når disse fremgangsmåder er veludført, giver de dig et transparent overblik over din MAS: du kan se, hvilke agenter der er langsomme, hvilke værktøjer der overbruges, hvor prompterne er for lange, og hvor kvalitetskontrolløkker som f.eks. LoopAgent iterere mere end forventet. Denne feedback-loop er afgørende for at finjustere både kvalitet og omkostninger over tid.

Ved at kombinere ADKs agentprimitiver, workflowmønstre og tilstandsmekanismer med Google Clouds referencearkitektur, sikkerhedsstak og operationelle værktøjer kan du designe multiagentsystemer, der ikke kun er smarte på papiret, men også implementeringsvenlige, styrbare og økonomisk levedygtige i produktion. Med udgangspunkt i simple forældre/underordnede agenter og videre til sekventielle, løkke- og parallelle orkestrationer får du et værktøjssæt til at omdanne agentidéer til robuste, vedligeholdelsesvenlige applikationer, der rent faktisk leverer forretningsværdi.