Questa pagina è stata tradotta dall'API Cloud Translation.

Crea sistemi multi-agente con ADK

1. Introduzione

Panoramica

Questo lab ti insegna a orchestrare sistemi complessi multi-agente utilizzando Google Agent Development Kit (Google ADK). Passerai da gerarchie di agenti semplici alla creazione di flussi di lavoro automatizzati e collaborativi.

Cosa creerai

Creerai due sistemi multi-agente distinti:

Un semplice agente di pianificazione di viaggi che impara a trasferire le conversazioni tra un agente di "brainstorming" e un agente di "pianificazione delle attrazioni".
Un generatore di proposte cinematografiche più avanzato che utilizza una "stanza degli autori" di agenti automatizzati (come un ricercatore, uno sceneggiatore e un critico) per lavorare insieme in un ciclo per creare la trama completa di un film.

Obiettivi didattici

Come creare relazioni tra agente principale e subagente.
Come scrivere dati nella sessione state da uno strumento.
Come leggere da state utilizzando i modelli di chiavi (ad es. {my_key?}).
Come utilizzare un SequentialAgent per i flussi di lavoro passo passo.
Come utilizzare un LoopAgent per creare cicli di perfezionamento iterativi.
Come utilizzare un ParallelAgent per eseguire attività indipendenti contemporaneamente.

2. Sistemi multi-agente

Agent Development Kit (ADK) consente agli sviluppatori di ottenere comportamenti più affidabili, sofisticati e in più passaggi dai modelli generativi. Invece di un prompt complesso, ADK ti consente di creare un flusso di più agenti più semplici che collaborano a un problema dividendo il lavoro.

Questo approccio presenta diversi vantaggi rispetto all'utilizzo di un singolo prompt monolitico:

Progettazione più semplice:è più semplice progettare e organizzare un flusso di agenti piccoli e specializzati che progettare un prompt grande e complesso.
Affidabilità:gli agenti specializzati sono più affidabili nelle loro attività specifiche rispetto a un agente grande e complesso.
Manutenibilità: è più facile correggere o migliorare un agente piccolo e specializzato senza danneggiare altre parti del sistema.
Modularità:gli agenti creati per un workflow possono essere facilmente riutilizzati in altri.

L'albero degli agenti gerarchico

Struttura ad albero che mostra gli agenti gerarchici

In ADK, gli agenti sono organizzati in una struttura ad albero. Questa gerarchia è fondamentale per controllare il flusso della conversazione, in quanto limita a quale agente può "passare" la conversazione. In questo modo, il comportamento del sistema è più prevedibile e più facile da eseguire il debug. I vantaggi includono:

Design intuitivo:la struttura si ispira ai team del mondo reale, il che la rende più facile da comprendere.
Flusso controllato:la gerarchia ti offre un controllo preciso sulla delega delle attività, il che è utile per il debug. Ad esempio, la struttura ad albero garantisce la chiamata dell'agente di scrittura dei report corretto, anche se ne hai due con descrizioni simili.

L'intera struttura inizia con il root_agent. Questo agente funge da genitore e può avere uno o più agenti secondari, che a loro volta possono essere genitori dei propri agenti secondari, formando l'albero.

3. Configurazione del progetto

Account Google

Se non hai ancora un Account Google personale, devi crearne uno.

Utilizza un account personale anziché un account di lavoro o della scuola.

Accedi a Google Cloud Console utilizzando un Account Google personale.

Abilita fatturazione

Riscatta 5 $di crediti Google Cloud (facoltativo)

Per partecipare a questo workshop, devi disporre di un account di fatturazione con del credito. Se prevedi di utilizzare la tua fatturazione, puoi saltare questo passaggio.

Fai clic su questo link e accedi con un Account Google personale.Vedrai una schermata simile a questa:
Fai clic sul pulsante FAI CLIC QUI PER ACCEDERE AI TUOI CREDITI.Verrà visualizzata una pagina per configurare il tuo profilo di fatturazione
Fai clic su Conferma.

Ora hai effettuato la connessione a un account di fatturazione di prova di Google Cloud Platform.

Screenshot della panoramica della fatturazione

Configurare un account di fatturazione personale

Se hai configurato la fatturazione utilizzando i crediti Google Cloud, puoi saltare questo passaggio.

Per configurare un account di fatturazione personale, vai qui per abilitare la fatturazione in Cloud Console.

Alcune note:

Il completamento di questo lab dovrebbe costare meno di 1 $in risorse cloud.
Per evitare ulteriori addebiti, puoi seguire i passaggi alla fine di questo lab per eliminare le risorse.
I nuovi utenti hanno diritto alla prova senza costi di 300$.

Crea un progetto (facoltativo)

Se non hai un progetto attuale che vuoi utilizzare per questa etichetta, creane uno nuovo qui.

4. Apri editor di Cloud Shell

Fai clic su questo link per andare direttamente all'editor di Cloud Shell.
Se ti viene richiesto di concedere l'autorizzazione in qualsiasi momento della giornata, fai clic su Autorizza per continuare.
Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
- Fai clic su Visualizza.
- Fai clic su Terminale.
Nel terminale, imposta il progetto con questo comando:
```
gcloud config set project [PROJECT_ID]
```
- Esempio:
```
gcloud config set project lab-project-id-example
```
- Se non ricordi l'ID progetto, puoi elencare tutti i tuoi ID progetto con:
```
gcloud projects list
```
Dovresti vedere questo messaggio:
```
Updated property [core/project].
```
Se vedi un WARNING e ti viene chiesto Do you want to continue (Y/n)?, probabilmente hai inserito l'ID progetto in modo errato. Premi n, premi Enter e prova a eseguire di nuovo il comando gcloud config set project.

5. Abilita API

Per utilizzare l'API Vertex AI e interagire con il modello Gemini, devi abilitare l'API Vertex AI nel tuo progetto Google Cloud.

Nel terminale, abilita l'API:

gcloud services enable aiplatform.googleapis.com

Di seguito sono riportate le sezioni aggiornate, che sostituiscono la creazione manuale dei file con le istruzioni per clonare il repository GitHub e installare le dipendenze.

Introduzione all'SDK Vertex AI per Python

Per interagire con i modelli ospitati su Vertex AI dalla tua applicazione Python, utilizzerai l'SDK Vertex AI per Python. Questo SDK semplifica il processo di invio di prompt, specifica i parametri del modello e riceve le risposte senza dover gestire direttamente le complessità delle chiamate API sottostanti.

Puoi trovare la documentazione completa per l'SDK Vertex AI per Python qui: Introduzione all'SDK Vertex AI per Python | Google Cloud.

6. Configurare l'ambiente del progetto

Clona il repository

Nel terminale, clona il repository contenente i file iniziali.
```
git clone --depth 1 https://github.com/GoogleCloudPlatform/devrel-demos.git
```
Il flag --depth 1 clona solo l'ultima versione, il che è più veloce.

Nel terminale, vai alla directory di lavoro corretta per questo lab.

cd devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems

Attivare un ambiente virtuale

Nel terminale, crea e attiva un ambiente virtuale utilizzando uv:
```
uv venv
source .venv/bin/activate
```
Nel terminale, installa google-adk e le altre dipendenze dal file requirements.txt:
```
uv pip install -r requirements.txt
```

Rivedere la struttura dei file

Ora che tutti i file sono stati creati, apri la cartella adk_multiagent_systems in Esplora risorse per visualizzare la struttura completa.

Nel menu dell'editor di Cloud Shell, seleziona File > Apri cartella….
Nella casella visualizzata, aggiungi le seguenti informazioni sulla cartella dopo il nome utente: devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems/. Fai clic su Ok.
Dovrebbe avere un aspetto simile a questo:
Il riquadro di esplorazione a sinistra verrà aggiornato. Ora dovresti visualizzare la struttura completa del progetto, con le sottodirectory parent_and_subagents e workflow_agents, pronte per i passaggi successivi.

Imposta le variabili di ambiente

Ti trovi già nella directory adk_multiagent_systems. Nel terminale, crea un file .env per archiviare le variabili di ambiente:
```
cloudshell edit .env
```

Incolla quanto segue nel file .env che si apre nell'editor:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT="[YOUR-PROJECT-ID]"
GOOGLE_CLOUD_LOCATION=global
MODEL="gemini-2.5-flash"

Sostituisci [YOUR-PROJECT-ID] con l'ID del tuo progetto Google Cloud effettivo. (ad es. PROJECT_ID = "google-cloud-labs")
Se non ricordi l'ID progetto, esegui questo comando nel terminale. Verrà visualizzato un elenco di tutti i tuoi progetti e dei relativi ID.
```
gcloud projects list
```
Nel terminale, copia questo file .env nelle directory dei sub-agenti in modo che possano accedere anche alle variabili:
```
cp .env parent_and_subagents/.env
cp .env workflow_agents/.env
```
La struttura dei file dovrebbe ora avere il seguente aspetto:

7. Esplorare i trasferimenti tra agenti principali, secondari e peer

La conversazione inizia sempre con root_agent. Per impostazione predefinita, un agente principale utilizza l'description dei suoi agenti secondari per decidere quando trasferire la conversazione. Puoi anche guidare questi trasferimenti in modo esplicito nel instruction del genitore utilizzando i name dei subagenti.

Proviamo.

Nell'editor di Cloud Shell, apri adk_multiagent_systems/parent_and_subagents/agent.py. Nota i tre agenti nel file agent.py:
- root_agent (denominato steering): pone all'utente una domanda per decidere a quale subagente trasferire la richiesta. Inizialmente, si basa solo sul description dei suoi subagenti.
- travel_brainstormer: aiuta l'utente a trovare destinazioni.
- attractions_planner: aiuta l'utente a elencare le cose da fare in un paese specifico.
Suggerimento:per leggere un file agent.py in ordine di flusso della conversazione, spesso è più facile iniziare a leggere dal root_agent in basso e procedere verso l'alto. Questo perché il codice Python richiede che definiamo i nostri subagenti prima di poterli aggiungere a un agente.
Rendi travel_brainstormer e attractions_planner subagenti di root_agent aggiungendo la seguente riga alla creazione di root_agent:
```
    sub_agents=[travel_brainstormer, attractions_planner]
```
Nota: la gerarchia degli agenti è definita solo dall'elenco sub_agents del genitore; i subagenti non hanno bisogno di un parametro parent.

Nel terminale, chatta con il tuo agente:

cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
adk run parent_and_subagents

Al prompt [user]: nel terminale, digita:

hello

Output di esempio (il tuo potrebbe essere leggermente diverso):

[steering]: Hi there! Do you already have a country in mind for your trip, or would you like some help deciding where to go?

Ora, comunica all'agente nel terminale:
```
I could use some help deciding.
```
Output di esempio (il tuo potrebbe essere leggermente diverso):
```
[travel_brainstormer]: Okay! To give you the best recommendations, I need to understand what you're looking for in a trip.
...
```
Nota il tag [travel_brainstormer]. Il controllo trasferito root_agent si basa solo sul description del subagente.
Al prompt user: nel terminale, digita exit e premi INVIO per terminare la conversazione.

Ora vediamo più nel dettaglio. In agent.py, aggiungi quanto segue a instruction di root_agent:

        If they need help deciding, send them to 'travel_brainstormer'.
        If they know what country they'd like to visit, send them to the 'attractions_planner'.

Nel terminale, esegui di nuovo l'agente:
```
adk run parent_and_subagents
```
Al prompt [user]: nel terminale, digita:
```
hello
```
Rispondi così:
```
I would like to go to Japan.
```
Output di esempio (il tuo potrebbe essere leggermente diverso):
```
[attractions_planner]: Okay, I can help you with that! Here are some popular attractions in Japan:
...
```
Nota il trasferimento a attractions_planner, come indicato dalle nuove istruzioni.
Ora rispondi con:
```
Actually I don't know what country to visit.
```
Output di esempio (il tuo potrebbe essere leggermente diverso):
```
[travel_brainstormer]: Okay! I can help you brainstorm some countries for travel...
```
Tieni presente che sei stato trasferito a travel_brainstormer, un peer di attractions_planner. Questa opzione è consentita per impostazione predefinita.
Se vuoi impedire il trasferimento, puoi impostare disallow_transfer_to_peers=True nell'agente attractions_planner.
Al prompt dell'utente, digita exit per terminare la sessione.

Riepilogo

In questa sezione hai appreso i concetti di base della gerarchia degli agenti e del flusso di conversazione:

La conversazione inizia sempre con root_agent.
Un agente principale può essere trasferito automaticamente a un agente secondario in base al suo description.
Puoi controllare esplicitamente questo flusso dando al genitore instruction da trasferire a un subagente tramite il suo name.
Per impostazione predefinita, gli agenti possono trasferire le chiamate agli agenti peer (fratelli nella gerarchia).

8. Utilizzare lo stato della sessione per archiviare e recuperare informazioni

Ogni conversazione ADK ha un Session, che include un dizionario dello stato della sessione. Questo stato è accessibile a tutti gli agenti, il che lo rende il modo perfetto per scambiarsi informazioni o mantenere i dati (ad esempio un elenco) durante la conversazione.

Per scoprire come aggiungere e leggere lo stato:

Torna al file adk_multiagent_systems/parent_and_subagents/agent.py

Incolla la seguente definizione di funzione dopo l'intestazione # Tools:

def save_attractions_to_state(
tool_context: ToolContext,
attractions: List[str]
) -> dict[str, str]:
    """Saves the list of attractions to state["attractions"].

    Args:
        attractions [str]: a list of strings to add to the list of attractions

    Returns:
        None
    """
    # Load existing attractions from state. If none exist, start an empty list
    existing_attractions = tool_context.state.get("attractions", [])

    # Update the 'attractions' key with a combo of old and new lists.
    # When the tool is run, ADK will create an event and make
    # corresponding updates in the session's state.
    tool_context.state["attractions"] = existing_attractions + attractions

    # A best practice for tools is to return a status message in a return dict
    return {"status": "success"}

In questo codice, nota:

La funzione riceve tool_context: ToolContext. Questo oggetto è il tuo gateway per la sessione.
La riga tool_context.state["attractions"] = ... legge e scrive direttamente nel dizionario di stato della sessione. L'ADK si occupa del resto.

Aggiungi lo strumento all'agente attractions_planner aggiungendo il parametro tools:
```
    tools=[save_attractions_to_state]
```
Aggiungi i seguenti punti elenco al instruction esistente dell'agente attractions_planner:
```
        - When they reply, use your tool to save their selected attraction and then provide more possible attractions.
        - If they ask to view the list, provide a bulleted list of { attractions? } and then suggest some more.
```
Nota la sezione tra parentesi graffe: { attractions? }. Questa funzionalità dell'ADK, modelli di chiavi, inserisce il valore della chiave attractions dallo stato nel prompt dell'agente. ? lo rende facoltativo, evitando errori se la chiave non esiste ancora.

Avvia l'interfaccia utente web dell'Agent Development Kit con il seguente comando nel terminale:

adk web

Output

INFO:     Started server process [2434]
INFO:     Waiting for application startup.
+-------------------------------------------------------+
| ADK Web Server started                                |
|                                                       |
| For local testing, access at http://localhost:8000.   |
+-------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Nel terminale Cloud Shell, fai clic sul pulsante Anteprima web e seleziona Cambia porta per visualizzare l'interfaccia web in una nuova scheda.
Inserisci il numero di porta 8000 e fai clic su Cambia e visualizza anteprima. Si apre una nuova scheda del browser con la UI di ADK Dev.
Dal menu a discesa Seleziona un agente a sinistra, scegli parent_and_subagents.
Inizia la conversazione con: hello
Dopo il saluto dell'operatore, rispondi con:
```
I'd like to go to Egypt.
```
Dovresti essere trasferito a attractions_planner e ricevere un elenco di attrazioni.
Scegli un'attrazione, ad esempio:
```
I'll go to the Sphinx
```
Dovresti ricevere una risposta come: Ok, ho salvato The Sphinx nella tua lista…
Fai clic sulla casella degli strumenti di risposta (contrassegnata da un segno di spunta) per visualizzare l'evento creato dalla risposta dello strumento.
Nota che include un campo azioni che include stateDelta che descrivono le modifiche allo stato.
Rispondi con un'altra attrazione dell'elenco dell'agente.
Nel menu di navigazione a sinistra, fai clic sulla "X" per uscire dalla visualizzazione dell'evento che hai esaminato in precedenza.
Nella barra laterale a sinistra, fai clic sulla scheda Stato. Ora puoi visualizzare l'array attractions nello stato della sessione, che dovrebbe contenere entrambi gli elementi selezionati.
Invia questo messaggio all'agente:
```
What is on my list?
```
L'agente dovrebbe ora leggere lo stato e restituire l'elenco.
Quando hai finito di sperimentare con l'agente, chiudi la scheda del browser web e premi Ctrl+C nel terminale Cloud Shell per arrestare il server.

Riepilogo della sezione

In questa sezione hai imparato a utilizzare lo stato Session per condividere i dati:

Per scrivere lo stato: scrivi nel dizionario di stato dall'interno di uno strumento, utilizzando l'oggetto tool_context.state (ad es. tool_context.state["my_list"] = [...]).
Per leggere lo stato: inserisci i dati di stato direttamente in instruction di un agente utilizzando i modelli di chiavi (ad es. Here is your list: {my_list?}).
Per esaminare lo stato: puoi monitorare lo stato della sessione in tempo reale nell'interfaccia utente di sviluppo dell'ADK utilizzando la scheda Stato.

9. Agenti workflow

Finora, hai visto come un agente principale trasferisce la richiesta a un agente secondario e poi attende l'utente. Gli agenti del workflow sono diversi: eseguono i relativi subagenti uno dopo l'altro in un flusso automatizzato, senza attendere l'input dell'utente.

È perfetto per attività automatizzate in più passaggi come una pipeline "Pianifica ed esegui" o "Bozza e rivedi". ADK fornisce tre agenti del workflow integrati per gestire questa operazione:

SequentialAgent
LoopAgent
ParallelAgent

Il resto di questo lab si concentrerà sulla creazione di un sistema multi-agente utilizzando questi tre agenti del flusso di lavoro.

Creerai un agente che sviluppa un documento di proposta per un nuovo film su un personaggio storico. Gli agenti si occuperanno di ricerca, scrittura iterativa e generazione di report.

Alla fine, il sistema avrà questo aspetto:

Diagramma di un sistema multi-agente film_concept_team

Creerai questo sistema un passo alla volta, iniziando dal flusso di lavoro più semplice.

10. Crea un sistema multi-agente con un SequentialAgent

Un SequentialAgent è un agente del flusso di lavoro che esegue i suoi subagenti in una sequenza semplice e lineare. Ogni agente nell'elenco sub_agents viene eseguito uno dopo l'altro, in ordine. È perfetto per le pipeline in cui le attività devono essere eseguite in un ordine specifico, come l'agente di presentazione di film che creerai ora.

Questa prima versione sarà strutturata nel seguente modo:

Film_concept_team multi-agent system step 1

Un root_agent (greeter) accoglierà l'utente e otterrà l'argomento del film.
Verrà quindi trasferito a un SequentialAgent denominato film_concept_team, che:
1. Esegui un agente researcher per ottenere informazioni da Wikipedia.
2. Esegui un agente screenwriter per utilizzare questi fatti per scrivere una trama.
3. Esegui un agente file_writer per salvare il grafico finale in un file.

Eseguiamolo.

Nell'editor di Cloud Shell, apri adk_multiagent_systems/workflow_agents/agent.py.
Leggi questo file di definizione dell'agente. Poiché i subagenti devono essere definiti prima di poter essere assegnati a un agente principale, per leggere il file nell'ordine del flusso conversazionale, puoi leggere gli agenti dal basso verso l'alto del file.
Nota lo strumento append_to_state. Questa funzione helper consente agli agenti di aggiungere dati a un elenco nello stato della sessione, ovvero il modo in cui researcher e screenwriter trasferiranno il proprio lavoro.
Prova l'agente. Nel terminale, avvia l'interfaccia web con il ricaricamento dinamico attivato:
```
cd ~/devrel-demos/ai-ml/build-multiagent-systems-with-adk/adk_multiagent_systems
adk web --reload_agents
```
Nota: se la porta 8000 è in uso, puoi eseguire l'operazione su una porta diversa, ad esempio adk web --reload_agents --port 8001.
Nel terminale Cloud Shell, fai clic sul pulsante Anteprima web e seleziona Cambia porta per visualizzare l'interfaccia web in una nuova scheda.
Inserisci il numero di porta 8000 e fai clic su Cambia e visualizza anteprima. Si apre una nuova scheda del browser con la UI di ADK Dev.
Dal menu a discesa Seleziona un agente, seleziona workflow_agents.
Inizia la conversazione con: hello. L'agente greeter risponderà.
Quando ti viene richiesto, inserisci un personaggio storico. Puoi utilizzare uno di questi o il tuo:
- Zhang Zhongjing
- Ada Lovelace
- Marco Aurelio
Ora sarà SequentialAgent a occuparsi della questione. Non vedrai alcun messaggio intermedio. researcher, screenwriter e file_writer verranno eseguiti uno dopo l'altro. L'agente risponderà solo al termine dell'intera sequenza.
Se non va a buon fine, puoi fare clic su + Nuova sessione in alto a destra e riprovare.
Una volta che l'agente conferma la scrittura del file, individua e apri il nuovo file .txt nella directory movie_pitches in Cloud Shell Editor per visualizzare l'output.
Nell'interfaccia utente di ADK Dev, fai clic sull'ultima icona dell'agente nella cronologia della chat per aprire la visualizzazione eventi.
La visualizzazione eventi mostra un grafico visivo dell'albero degli agenti. Puoi vedere come greeter ha chiamato film_concept_team, che a sua volta ha chiamato ciascuno dei suoi subagenti in ordine.
Puoi fare clic sulle schede Richiesta e Risposta per qualsiasi agente nel grafico per esaminare i dati esatti che sono stati trasmessi, incluso lo stato della sessione.

Riepilogo della sezione

In questa sezione hai imparato a utilizzare un agente del flusso di lavoro:

Un SequentialAgent esegue i suoi subagenti uno alla volta, in ordine, senza attendere l'input dell'utente tra i passaggi.
Si tratta di un "flusso di lavoro" perché l'utente parla con root_agent, che poi passa il lavoro a SequentialAgent per il completamento.
I subagenti nella sequenza utilizzano lo stato della sessione (ad es. { PLOT_OUTLINE? }) per accedere al lavoro degli agenti precedenti.
Puoi utilizzare il grafico degli eventi nella UI per sviluppatori per visualizzare ed eseguire il debug dell'intero flusso di lavoro da agente ad agente.

11. Aggiungere un LoopAgent per il lavoro iterativo

LoopAgent è un agente del flusso di lavoro che esegue i relativi subagenti in sequenza e poi li ripete, a partire dall'inizio. Questo "ciclo" continua finché non viene soddisfatta una condizione, ad esempio il raggiungimento di un conteggio di max_iterations o una chiamata di un subagente allo strumento exit_loop integrato.

È utile per le attività che richiedono un perfezionamento iterativo. Aggiungerai questo LoopAgent per creare una "stanza degli autori" per l'agente di presentazione del tuo film. In questo modo, un researcher, un screenwriter e un nuovo agente critic lavorano in un ciclo, migliorando la trama a ogni passaggio finché l'agente critic non decide che è pronta. In questo modo, l'agente può gestire anche input utente più vaghi (ad esempio "un medico antico") consentendogli di fare ricerche e perfezionare un'idea.

Film_concept_team multi-agent system step 2

Per apportare queste modifiche:

In adk_multiagent_systems/workflow_agents/agent.py, aggiungi l'importazione per exit_loop (vicino alle altre importazioni di google.adk):
```
from google.adk.tools import exit_loop
```

Aggiungi il nuovo agente critic. L'agente esaminerà la trama. Se è buono, chiama exit_loop. In caso contrario, aggiunge il feedback allo stato per il ciclo successivo.
Incolla la seguente definizione dell'agente nella sezione # Agents:

critic = Agent(
    name="critic",
    model=model_name,
    description="Reviews the outline so that it can be improved.",
    instruction="""
    INSTRUCTIONS:
    Consider these questions about the PLOT_OUTLINE:
    - Does it meet a satisfying three-act cinematic structure?
    - Do the characters' struggles seem engaging?
    - Does it feel grounded in a real time period in history?
    - Does it sufficiently incorporate historical details from the RESEARCH?

    If the PLOT_OUTLINE does a good job with these questions, exit the writing loop with your 'exit_loop' tool.
    If significant improvements can be made, use the 'append_to_state' tool to add your feedback to the field 'CRITICAL_FEEDBACK'.
    Explain your decision and briefly summarize the feedback you have provided.

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    RESEARCH:
    { research? }
    """,
    before_model_callback=log_query_to_model,
    after_model_callback=log_model_response,
    tools=[append_to_state, exit_loop]
)

Crea il writers_room LoopAgent. Contiene i tre agenti che funzioneranno nel ciclo.
Incolla il seguente codice sopra la definizione dell'agente film_concept_team:
```
writers_room = LoopAgent(
    name="writers_room",
    description="Iterates through research and writing to improve a movie plot outline.",
    sub_agents=[
        researcher,
        screenwriter,
        critic
    ],
    max_iterations=5,
)
```
Prendi nota del parametro max_iterations=5. Si tratta di una misura di sicurezza fondamentale per evitare loop infiniti, anche quando è presente una condizione di uscita.

Aggiorna l'intent film_concept_team SequentialAgent per utilizzare il nuovo loop writers_room. Sostituisci researcher e screenwriter con il singolo agente writers_room.Sostituisci la definizione film_concept_team esistente con questa:

film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        writers_room,
        file_writer
    ],
)

Torna alla scheda ADK Dev UI e fai clic su + Nuova sessione in alto a destra.
Inizia una nuova conversazione con: hello
Quando ti viene chiesto, fornisci all'agente un argomento più ampio. Ecco alcune idee:
- un designer industriale che ha creato prodotti per le masse
- un cartografo (un creatore di mappe)
- quel ragazzo che ha fatto produrre più cibo ai raccolti
L'agente ora eseguirà il ciclo. Nell'interfaccia utente di sviluppo dell'ADK, vedrai i log man mano che gli agenti vengono eseguiti più volte (ad es. "[researcher]", "[screenwriter]", "[critic]", "[researcher]", "[screenwriter]", "[critic]...").
Al termine del ciclo, l'agente scriverà il file. Esamina il file generato nella directory adk_multiagent_systems/movie_pitches.
Esamina il grafico degli eventi nella UI di sviluppo per visualizzare la struttura del ciclo.

Riepilogo della sezione

In questa sezione hai imparato a utilizzare LoopAgent:

Un LoopAgent è un agente del workflow che ripete la sua sequenza di subagenti, creando un "ciclo interno" per le attività iterative.
Gli agenti all'interno del ciclo utilizzano lo stato della sessione per passare il lavoro (ad es. PLOT_OUTLINE) e feedback (ad es. CRITICAL_FEEDBACK) tra loro nei passaggi successivi.
Il ciclo può essere interrotto raggiungendo un limite di max_iterations o da un agente che chiama lo strumento exit_loop.

12. Utilizzare un ParallelAgent per "distribuire e raccogliere"

ParallelAgent è un agente del flusso di lavoro che esegue tutti i suoi agenti secondari contemporaneamente (in parallelo). Questo è utile per le attività che possono essere suddivise in sottoattività indipendenti, come l'esecuzione di due diversi job di ricerca.

Utilizzerai un ParallelAgent per creare un "team di preproduzione" che lavora in parallelo. Un agente studierà il potenziale al botteghino, mentre un altro farà brainstorming sulle idee di casting. Questo pattern viene spesso chiamato "fan out and gather": l'ParallelAgent "distribuisce" il lavoro e un agente successivo (il nostro file_writer) "raccoglie" i risultati.

Film_concept_team multi-agent system step 3

Il flusso finale dell'agente sarà:

L'greeter (radice) avvia la chat.
Viene trasferito a film_concept_team (SequentialAgent), che esegue:
- Il writers_room (LoopAgent) per creare il grafico.
- La nuova preproduction_team (ParallelAgent) per fare ricerche su incassi e casting contemporaneamente.
- file_writer per raccogliere tutti i risultati e salvare il file.

Per apportare queste modifiche:

In adk_multiagent_systems/workflow_agents/agent.py, incolla il nuovo ParallelAgent e i relativi subagenti sotto l'intestazione # Agents.

box_office_researcher = Agent(
    name="box_office_researcher",
    model=model_name,
    description="Considers the box office potential of this film",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    Write a report on the box office potential of a movie like that described in PLOT_OUTLINE based on the reported box office performance of other recent films.
    """,
    output_key="box_office_report"
)

casting_agent = Agent(
    name="casting_agent",
    model=model_name,
    description="Generates casting ideas for this film",
    instruction="""
    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    INSTRUCTIONS:
    Generate ideas for casting for the characters described in PLOT_OUTLINE
    by suggesting actors who have received positive feedback from critics and/or
    fans when they have played similar roles.
    """,
    output_key="casting_report"
)

preproduction_team = ParallelAgent(
    name="preproduction_team",
    sub_agents=[
        box_office_researcher,
        casting_agent
    ]
)

Aggiorna l'elenco sub_agents di SequentialAgent film_concept_team in modo da includere il nuovo preproduction_team (tra writers_room e file_writer).Sostituisci la definizione film_concept_team esistente con questa:

film_concept_team = SequentialAgent(
    name="film_concept_team",
    description="Write a film plot outline and save it as a text file.",
    sub_agents=[
        writers_room,
        preproduction_team,
        file_writer
    ],
)

Aggiorna l'instruction dell'agente file_writer in modo che "raccolga" i nuovi report dallo stato e li aggiunga al file.
Sostituisci la stringa instruction per file_writer con questa:

    instruction="""
    INSTRUCTIONS:
    - Create a marketable, contemporary movie title suggestion for the movie described in the PLOT_OUTLINE.
    If a title has been suggested in PLOT_OUTLINE, you can use it, or replace it with a better one.
    - Use your 'write_file' tool to create a new txt file with the following arguments:
    - for a filename, use the movie title
    - Write to the 'movie_pitches' directory.
    - For the 'content' to write, include:
    - The PLOT_OUTLINE
    - The BOX_OFFICE_REPORT
    - The CASTING_REPORT

    PLOT_OUTLINE:
    { PLOT_OUTLINE? }

    BOX_OFFICE_REPORT:
    { box_office_report? }

    CASTING_REPORT:
    { casting_report? }
    """,

Torna alla scheda della UI di ADK Dev e fai clic su + Nuova sessione.
Inserisci hello per iniziare la conversazione.
Quando richiesto, inserisci una nuova idea per un personaggio. Ecco alcune idee:
- l'attrice che ha inventato la tecnologia per il Wi-Fi
- uno chef entusiasmante
- protagonisti delle esposizioni delle fiere mondiali
Quando l'agente completa il suo lavoro, esamina il file finale nella directory adk_multiagent_systems/movie_pitches. Ora dovrebbe contenere la trama, il report sugli incassi e il report sul cast in un unico documento.

Riepilogo della sezione

In questa sezione hai imparato a utilizzare ParallelAgent:

Un ParallelAgent "fans out" work, running all its sub-agents at the same time, rather than in a sequence.
Questo è molto efficiente per le attività che non dipendono l'una dall'altra (come la ricerca di due argomenti diversi).
I risultati degli agenti paralleli vengono "raccolti" da un agente successivo. A questo scopo, gli agenti paralleli salvano il proprio lavoro nello stato della sessione (utilizzando output_key) e un agente finale (come file_writer) legge queste chiavi.

13. Agenti del workflow personalizzati

Quando gli agenti del flusso di lavoro predefiniti di SequentialAgent, LoopAgent e ParallelAgent non sono sufficienti per le tue esigenze, CustomAgent offre la flessibilità di implementare una nuova logica del flusso di lavoro.

Puoi definire pattern per il controllo del flusso, l'esecuzione condizionale o la gestione dello stato tra i sub-agenti. Ciò è utile per flussi di lavoro complessi, orchestrazioni stateful o per l'integrazione di logiche di business personalizzate nel livello di orchestrazione del framework.

La creazione di un CustomAgent non rientra nell'ambito di questo lab, ma è bene sapere che esiste se ne hai bisogno.

14. Complimenti!

Hai creato correttamente un sofisticato sistema multi-agente utilizzando Google Agent Development Kit (ADK). Sei passato da una semplice relazione di agenti principali/secondari all'orchestrazione di workflow complessi e automatizzati in grado di ricercare, scrivere e perfezionare un progetto creativo.

Riepilogo

In questo lab hai:

Organizza gli agenti in una struttura gerarchica con relazioni tra agente principale e secondario.
Trasferimenti da agente ad agente controllati, sia automaticamente (utilizzando description) sia esplicitamente (utilizzando instruction).
Utilizzato uno strumento per scrivere dati nel dizionario tool_context.state.
Utilizzo di modelli di chiavi (ad es. { PLOT_OUTLINE? }) per leggere lo stato della sessione e guidare il prompt di un agente.
È stato implementato un SequentialAgent per creare un workflow semplice e passo passo (ricerca -> scrittura -> salvataggio).
Utilizzato un LoopAgent con un agente critic e lo strumento exit_loop per creare un ciclo di perfezionamento iterativo.
Ha utilizzato un ParallelAgent per "distribuire" le attività indipendenti (come la ricerca di casting e box office) da eseguire contemporaneamente.

Sperimentazione continua

Esistono molti modi per approfondire ciò che hai imparato. Ecco alcuni esempi:

Aggiungi altri agenti:prova ad aggiungere un nuovo agente al tuo preproduction_team ParallelAgent. Ad esempio, potresti creare un marketing_agent che scriva uno slogan per il film in base alla PLOT_OUTLINE.
Aggiungi altri strumenti:fornisci al tuo agente researcher altri strumenti. Potresti creare uno strumento che utilizza un'API Google Search per trovare informazioni che non sono presenti su Wikipedia.
Esplora CustomAgent: il lab ha menzionato CustomAgent per i flussi di lavoro che non rientrano nei modelli standard. Prova a crearne uno che, ad esempio, esegua un agente in modo condizionale solo se esiste una chiave specifica nello stato della sessione.

Crea sistemi multi-agente con ADK

1. Introduzione

Panoramica

Cosa creerai

Obiettivi didattici

2. Sistemi multi-agente

L'albero degli agenti gerarchico

3. Configurazione del progetto

Account Google

Accedi alla console Google Cloud

Abilita fatturazione

Riscatta 5 $di crediti Google Cloud (facoltativo)

Configurare un account di fatturazione personale

Crea un progetto (facoltativo)

4. Apri editor di Cloud Shell

5. Abilita API

Introduzione all'SDK Vertex AI per Python

6. Configurare l'ambiente del progetto

Clona il repository

Attivare un ambiente virtuale

Rivedere la struttura dei file

Imposta le variabili di ambiente

7. Esplorare i trasferimenti tra agenti principali, secondari e peer

Riepilogo

8. Utilizzare lo stato della sessione per archiviare e recuperare informazioni

Riepilogo della sezione

9. Agenti workflow

10. Crea un sistema multi-agente con un SequentialAgent

Riepilogo della sezione

11. Aggiungere un LoopAgent per il lavoro iterativo

Riepilogo della sezione

12. Utilizzare un ParallelAgent per "distribuire e raccogliere"

Riepilogo della sezione

13. Agenti del workflow personalizzati

14. Complimenti!

Riepilogo

Sperimentazione continua