Creazione di agenti AI con ADK: orchestrazione dei workflow dei grafi

1. Panoramica

Per soddisfare una richiesta di viaggio con più vincoli (ad esempio, pianificare una gita di un giorno a Kyoto con un budget di 100 $, templi storici, ramen locale e nessun ART Museum d'arte moderna), è necessario estrarre preferenze strutturate, ricercare i luoghi contemporaneamente, sintetizzare una bozza dettagliata e verificare il costo totale prima di rispondere. In ADK 1.x, l'orchestrazione di queste fasi richiedeva l'annidamento dei wrapper SequentialAgent, ParallelAgent e LoopAgent, il salvataggio di ogni output intermedio nello stato della sessione e l'attivazione di una chiamata allo strumento LLM aggiuntiva solo per uscire da un loop di perfezionamento.

In questo codelab, creerai un pianificatore di viaggi multi-agente su Agent Platform utilizzando i workflow dei grafi di Agent Development Kit (ADK) 2 (Workflow). In tre fasi progressive, collegherai nodi Agent specialistici (basati su gemini-3.8-flash) in una catena di archi sequenziale (node_input), eseguirai il fan-out di ricercatori google_search simultanei sincronizzati con JoinNode e applicherai regole di budget e regole esclusive con un router Python deterministico (Event(route=...)) che salta il perfezionamento ogni volta che la bozza iniziale supera l'audit.

Serie Creazione di agenti AI con ADK: questo codelab autonomo continua la storia del pianificatore di viaggi di Le basi, Strumenti a disposizione e Orchestrazione dei flussi di lavoro degli agenti utilizzando il runtime del grafo unificato di ADK 2.

Prerequisiti

• Conoscenza di base della programmazione in Python
• Familiarità con i concetti di AI generativa e i concetti fondamentali degli agenti AI

Cosa imparerai

• Come dichiarare una pipeline multi-agente in ADK 2 utilizzando le tuple di archi Workflow
• In che modo ADK 2 passa gli output direttamente lungo gli archi come node_input e associa le chiavi di stato della sessione come parametri della funzione
• Come suddividere i rami di ricerca simultanei e unire i relativi output con JoinNode
• Come instradare in modo deterministico i cicli di maker-checker limitati in Python con Event(route=...)
• Come ispezionare i grafici dei workflow compilati, le cronologie di esecuzione parallela e i delta di stato nell'interfaccia utente web di ADK

Cosa serve

• Un Account Google (utilizza un account @gmail.com personale se richiedi i crediti per il workshop)
• Un link per i crediti del workshop fornito dall'insegnante (oltre alla fotocamera dello smartphone per scansionare il codice QR) o un account di fatturazione Cloud attivo
• Google Chrome (è consigliata una finestra Incognito per evitare di combinare account personali e di lavoro)

Suggerimento Incognito: apri questo codelab in una finestra Incognito in modo che ogni link alla console Cloud e a Cloud Shell si apra nella stessa sessione.

2. (Facoltativo) Richiedi crediti Google Cloud

Se partecipi a un workshop con un link ai crediti per l'evento, richiedi il tuo credito del Google Developer Program per eseguire il provisioning di un account di fatturazione senza carta di credito.

Utilizzi il tuo account di fatturazione? Vai a Crea un progetto Google Cloud (facoltativo) (o Configura l'ambiente se hai già un progetto). Se hai bisogno di un nuovo account di fatturazione senza crediti per l'evento, consulta Crea un account di fatturazione Cloud o Prova senza costi di Google Cloud.

Richiedi il tuo credito per l'evento

⚠️ Utilizza un account Gmail personale: gli account Google Workspace aziendali o scolastici non possono richiedere i crediti per gli eventi del workshop.

1. Apri il link dei crediti del workshop in una finestra di navigazione in incognito e accedi con il tuo account @gmail.com.
2. In Richiedi il tuo vantaggio, fai clic su Richiedi credito:

3. Se ti viene chiesto di creare un profilo Google Developer Program, compila il modulo.
4. Quando viene visualizzato il messaggio Scansiona per verificare che sei un essere umano, scansiona il codice QR con lo smartphone e completa la verifica (aggiorna la pagina e fai di nuovo clic su Richiedi credito se il codice QR non viene visualizzato):

5. Verifica che venga visualizzato il messaggio Hai richiesto correttamente il tuo credito per l'evento, quindi fai clic su Apri account di fatturazione:

🔍 Controlla il tuo lavoro

La configurazione dell'account di fatturazione richiede fino a 3 minuti:

1. Apri Fatturazione Cloud (o copia l'URL nella finestra di navigazione in incognito) e seleziona I tuoi account di fatturazione:

https://console.cloud.google.com/billing

2. Aggiorna la pagina finché lo stato del tuo account GDP Credit non diventa Attivo:

3. Crea un progetto Google Cloud (facoltativo)

Crea un progetto Google Cloud dedicato in modo che tutte le risorse di questo codelab rimangano isolate e facili da eliminare.

Hai già un progetto? Se hai già un progetto con fatturazione abilitata o un progetto di workshop pre-provisioning, vai a Configura l'ambiente.

1. Apri Crea un progetto (o copia l'URL nella finestra Incognito):

https://console.cloud.google.com/projectcreate

2. Inserisci i dettagli del progetto:
   • Nome progetto: ad esempio google-cloud-workshop
   • Account di fatturazione (se visualizzato): seleziona GDP Credit (o il tuo account di fatturazione attivo)
   • Risorsa padre: Nessuna organizzazione (o seleziona la tua organizzazione, se necessario)
3. Prendi nota dell'ID progetto generato sotto il nome del progetto, quindi fai clic su Crea:

🔍 Controlla il tuo lavoro

Fai clic su Notifiche nella barra degli strumenti in alto a destra e poi su Seleziona progetto al termine della creazione del progetto:

4. Configura l'ambiente

Configura Google Cloud Shell, abilita l'API Agent Platform e crea un ambiente virtuale Python 3.12 isolato con uv.

Continuare da un precedente laboratorio ADK? Se l'ID progetto e l'API Agent Platform sono già configurati in questa sessione di Cloud Shell, vai direttamente a Crea un ambiente virtuale Python e installa l'ADK in modo che ~/adk-graph-agents/.venv venga creato correttamente.

Suggerimento per il terminale locale: preferisci utilizzare un terminale locale anziché Cloud Shell? Sostituisci i comandi cloudshell edit filename con il tuo editor preferito (ad esempio code filename o nano filename) e il gioco è fatto.

Configura Cloud Shell

1. Fai clic su Attiva Cloud Shell (>_) nella barra degli strumenti della console Google Cloud o apri direttamente Google Cloud Shell (o copia l'URL nella finestra Incognito):

https://shell.cloud.google.com/?show=ide,terminal

2. Fai clic su Autorizza, se richiesto:

3. Seleziona l'ID progetto Google Cloud attivo dal menu numerato nel terminale:

unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
  [ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done

Dovresti visualizzare un output simile al seguente (per i progetti senza tag viene stampata anche una riga informativa [environment: untagged]):

1) google-cloud-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].

Verifica che l'ID progetto selezionato sia evidenziato in giallo nel prompt di Cloud Shell:

Abilita le API richieste

Abilita l'API Agent Platform in modo che i tuoi agenti ADK possano richiamare i modelli Gemini:

gcloud services enable aiplatform.googleapis.com

Dovresti visualizzare un output simile al seguente:

Operation "operations/acat.p2-..." finished successfully.

Crea un ambiente virtuale Python e installa l'ADK

Perché uv? Scritto in Rust, uv crea ambienti Python e installa pacchetti in pochi secondi. Scopri di più nella documentazione di uv.

Crea l'area di lavoro ~/adk-graph-agents e attiva un ambiente virtuale Python 3.12:

cd ~
mkdir -p adk-graph-agents && cd ~/adk-graph-agents

which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

uv venv .venv --python 3.12
source .venv/bin/activate

Verifica che il prefisso (.venv) venga visualizzato all'inizio del prompt del terminale:

Installa ADK 2 nell'ambiente virtuale attivo:

uv pip install --no-cache "google-adk==2.14.0"

🔍 Controlla il tuo lavoro

Verifica la versione installata della CLI adk:

adk --version

Dovresti visualizzare un output simile al seguente:

adk, version 2.14.0

Suggerimento per il ripristino della sessione: se la scheda di Cloud Shell si disconnette in un secondo momento, torna all'area di lavoro e riattiva l'ambiente con cd ~/adk-graph-agents && source .venv/bin/activate.

5. Crea lo scaffold dell'agente di viaggio

Genera il pacchetto travel_planner iniziale con adk create e testa la base di riferimento predefinita per un singolo agente in adk web.

Genera il pacchetto iniziale

Esegui adk create da ~/adk-graph-agents:

cd ~/adk-graph-agents
adk create travel_planner

Seleziona le seguenti opzioni quando richiesto (se viene visualizzato Enable telemetry? [Y/n]: alla prima esecuzione, premi Invio o digita n e premi Invio):

1. Scegli un modello per l'agente root: digita 2 per selezionare gemini-3.8-flash (l'opzione 1 seleziona gemini-3.5-flash) e premi Invio.
2. Scegli un backend: digita 2 per selezionare il backend Agent Platform di Google Cloud (opzione 2 nel menu della CLI di seguito) e premi Invio.
3. Inserisci l'ID progetto Google Cloud: premi Invio per accettare l'ID progetto rilevato tra parentesi.
4. Inserisci la regione Google Cloud: digita global (per utilizzare l'endpoint Gemini globale) e premi Invio.

adk create scrive GOOGLE_GENAI_USE_ENTERPRISE=1, l'ID progetto e GOOGLE_CLOUD_LOCATION=global in travel_planner/.env, in modo che le tue credenziali rimangano invariate quando sostituisci agent.py in un secondo momento.

Dovresti visualizzare un output simile al seguente:

Choose a model for the root agent:
1. gemini-3.5-flash
2. gemini-3.8-flash
3. Other models (fill later)
Choose model (1, 2, 3): 2
1. Google AI
2. Vertex AI
3. Login with Google
Choose a backend (1, 2, 3): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [google-cloud-workshop-4210]:
Enter Google Cloud region [us-central1]: global

Agent created in /home/your_username/adk-graph-agents/travel_planner:
- .env
- .gitignore
- __init__.py
- agent.py

⚠️  WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env.

Next steps:
- Chat with your agent in the terminal: adk run travel_planner
- Or in the browser: adk web .
- Have your coding agent evaluate and deploy it: uvx google-agents-cli setup
  (other install options: https://adk.dev/get-started/agents-cli/)

Apri ~/adk-graph-agents nell'editor di codice di Cloud Shell:

which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/adk-graph-agents || true

Nota sul riavvio del terminale: l'esecuzione di cloudshell workspace ricarica la finestra di Cloud Shell e riavvia la shell. Riattiva .venv una volta ricaricato il riquadro del terminale.

Riattiva l'ambiente virtuale nel terminale ricaricato:

cd ~/adk-graph-agents
source .venv/bin/activate

Testa l'agente singolo iniziale

Avvia l'interfaccia utente web dell'ADK per osservare come un singolo agente iniziale non orchestrato risponde a un prompt di viaggio:

cd ~/adk-graph-agents
adk web --allow_origins "*"

Fai clic sull'icona Anteprima web nella barra degli strumenti di Cloud Shell in alto a destra, seleziona Cambia porta, inserisci 8000 e fai clic su Cambia e visualizza anteprima:

🔍 Controlla il tuo lavoro

Seleziona travel_planner nel menu a discesa in alto a sinistra di adk web e invia "Help me plan a trip to Japan":

Dovresti vedere una risposta conversazionale in un unico passaggio nel riquadro della chat (con una singola chiamata root_agent in Eventi):

root_agent -> responds in one pass without structured preference extraction, live search, or budget verification

Premi Ctrl + C nel terminale Cloud Shell per interrompere adk web prima di modificare i file nel passaggio successivo.

6. Crea un workflow di grafi lineari

Crea il tuo primo ADK 2 Workflow: una catena sequenziale che collega il punto di ingresso riservato "START" a user_profiler_agent e itinerary_synthesizer_agent (qualsiasi nodo senza archi in uscita funge da nodo terminale). Ogni edge (a, b) esegue automaticamente i nodi Agent (un alias per LlmAgent) in modalità single_turn isolata e fornisce l'output del nodo a come node_input (il messaggio utente in arrivo) al nodo b, mentre {user_preferences} in una stringa di istruzioni interpola la chiave dello stato della sessione corrispondente salvata tramite output_key.

Crea gli specialisti iniziali

Assicurati che adk web sia interrotto (Ctrl + C), quindi apri un nuovo file denominato travel_planner/specialists.py:

cloudshell edit ~/adk-graph-agents/travel_planner/specialists.py

Incolla il seguente codice in travel_planner/specialists.py per definire user_profiler_agent e itinerary_synthesizer_agent (importando google_search in anticipo per il passaggio successivo):

from google.adk import Agent
from google.adk.tools import google_search

MODEL = "gemini-3.8-flash"

# --- Specialist 1: The User Profiler ---
user_profiler_agent = Agent(
    model=MODEL,
    name="user_profiler_agent",
    description="Extracts travel preferences and constraints from user input.",
    instruction="""
        Extract destination, duration (default 1 day), budget, interests, and exclusions.
        Return a single JSON object with keys: "destination", "duration", "budget", "interests", "exclusions".
    """,
    output_key="user_preferences",  # Saved for multi-hop constraints downstream
)

# --- Specialist 2: The Synthesizer ---
itinerary_synthesizer_agent = Agent(
    model=MODEL,
    name="itinerary_synthesizer_agent",
    description="Compiles preferences and research into a final Markdown itinerary.",
    instruction="""
        You are an elite Travel Concierge. Using the incoming input and
        User Preferences ({user_preferences}), write a Markdown itinerary
        with an itemized USD and local currency cost breakdown.
    """,
    output_key="final_itinerary",
)

node_input, output_key e MODEL: a differenza di ADK 1 SequentialAgent e ParallelAgent (dove ogni esperto richiedeva output_key), ADK 2 Workflow fornisce l'output di ogni nodo direttamente al nodo successivo tramite node_input. Riserva output_key solo per i valori a cui si fa riferimento più hop a valle con segnaposto di istruzioni {key} (come {user_preferences} e {final_itinerary}). Poiché Workflow non propaga un modello principale ai nodi del grafico, la definizione di MODEL una volta all'inizio di specialists.py ti consente di eseguire l'upgrade di tutti i nodi in un'unica riga.

Definisci la catena di archi sequenziali

Apri un nuovo file denominato travel_planner/workflows.py:

cloudshell edit ~/adk-graph-agents/travel_planner/workflows.py

Incolla la seguente definizione di Workflow (dove una tupla di 3 o più nodi viene compilata in una catena sequenziale da "START"):

from google.adk import Workflow
from .specialists import (
    itinerary_synthesizer_agent,
    user_profiler_agent,
)

# 1. SEQUENTIAL GRAPH: START -> user_profiler_agent -> itinerary_synthesizer_agent
travel_workflow = Workflow(
    name="travel_workflow",
    description="Orchestrates the end-to-end travel planning process as a graph workflow.",
    edges=[
        ("START", user_profiler_agent, itinerary_synthesizer_agent),
    ],
)

Esponi il workflow come root_agent

Apri travel_planner/agent.py:

cloudshell edit ~/adk-graph-agents/travel_planner/agent.py

Sostituisci l'intero contenuto di travel_planner/agent.py con queste due righe:

from .workflows import travel_workflow

root_agent = travel_workflow

Configurazione dell'entrypoint una tantum: poiché agent.py riesporta travel_workflow come root_agent, ogni upgrade del grafo che esegui in workflows.py diventa effettivo automaticamente senza dover modificare nuovamente agent.py.

🔍 Controlla il tuo lavoro

Avvia adk web da ~/adk-graph-agents:

cd ~/adk-graph-agents
adk web --allow_origins "*"

Apri l'anteprima web sulla porta 8000, fai clic su + Nuova sessione e invia:

Help me plan a trip to Kyoto

Nella visualizzazione Eventi, dovresti vedere una sequenza di eventi simile alla seguente:

1. user_profiler_agent -> outputs JSON {"destination": "Kyoto", "duration": "1 day", ...} and writes state["user_preferences"]
2. itinerary_synthesizer_agent -> receives preferences via node_input and outputs the Markdown itinerary

Fai clic su un evento qualsiasi in Eventi e sull'icona Grafico (account_tree nella barra degli strumenti dei dettagli dell'evento) per esaminare la topologia START -> user_profiler_agent -> itinerary_synthesizer_agent compilata, quindi controlla la scheda Stato per verificare che user_preferences e final_itinerary siano compilati.

Premi Ctrl + C nel terminale per interrompere adk web prima di continuare.

7. Fan-out e join con JoinNode

Basare l'itinerario su dati web in tempo reale aggiungendo due esperti google_search contemporaneamente (activity_finder_agent e restaurant_finder_agent) e sincronizzandoli con JoinNode:

• Tupla di fan-out: l'inserimento di (activity_finder_agent, restaurant_finder_agent) all'interno della tupla perimetrale fornisce l'output di user_profiler_agent come node_input a entrambi i ricercatori contemporaneamente.
• Barriera fan-in (JoinNode): posizionando JoinNode(name="research_join") subito dopo la tupla, si attende che ogni ramo in entrata venga completato e passi un dict ({"activity_finder_agent": ..., "restaurant_finder_agent": ...}) unito come node_input a itinerary_synthesizer_agent anziché attivare la sintesi due volte.

Aggiungi gli esperti di ricerca

Verifica che adk web sia stato arrestato (Ctrl + C), quindi apri travel_planner/specialists.py:

cloudshell edit ~/adk-graph-agents/travel_planner/specialists.py

Aggiungi activity_finder_agent e restaurant_finder_agent alla fine di travel_planner/specialists.py (nessuno dei due richiede output_key perché research_join inoltra entrambi gli output direttamente tramite node_input):

# --- Specialist 3: The Activity Finder ---
activity_finder_agent = Agent(
    model=MODEL,
    name="activity_finder_agent",
    description="Finds 3 attractions matching the user's destination and interests.",
    instruction="""
        Using the travel preferences in the input, call google_search to find 3 specific attractions
        (including budget-friendly options).
        Return a JSON list with keys: "attraction_name", "estimated_cost_local", "estimated_cost_usd", "notes".
    """,
    tools=[google_search],
)

# --- Specialist 4: The Restaurant Finder ---
restaurant_finder_agent = Agent(
    model=MODEL,
    name="restaurant_finder_agent",
    description="Finds 3 restaurants matching the destination and budget.",
    instruction="""
        Using the travel preferences in the input, call google_search to find 3 highly-rated restaurants
        across price points.
        Return a JSON list with keys: "restaurant_name", "cuisine", "estimated_cost_local", "estimated_cost_usd".
    """,
    tools=[google_search],
)

Strumento di conversione di valuta facoltativo del Lab 2: poiché google_search rimane isolato sui due nodi di ricerca, puoi anche collegare la funzione get_fx_rate personalizzata di Potenziare con gli strumenti a itinerary_synthesizer_agent (tools=[get_fx_rate]) per la conversione del tasso di cambio in tempo reale.

Aggiungi fan-out e JoinNode a workflows.py

Apri travel_planner/workflows.py:

cloudshell edit ~/adk-graph-agents/travel_planner/workflows.py

Sostituisci l'intero contenuto di travel_planner/workflows.py con il grafico fan-out e JoinNode:

from google.adk import Workflow
from google.adk.workflow import JoinNode
from .specialists import (
    activity_finder_agent,
    itinerary_synthesizer_agent,
    restaurant_finder_agent,
    user_profiler_agent,
)

research_join = JoinNode(name="research_join")

# 2. FAN-OUT / FAN-IN GRAPH: Profile -> (Activities || Restaurants) -> Join -> Synthesize
travel_workflow = Workflow(
    name="travel_workflow",
    description="Orchestrates the end-to-end travel planning process as a graph workflow.",
    edges=[
        (
            "START",
            user_profiler_agent,
            (activity_finder_agent, restaurant_finder_agent),
            research_join,
            itinerary_synthesizer_agent,
        ),
    ],
)

🔍 Controlla il tuo lavoro

Avvia adk web per testare la ricerca simultanea e la sincronizzazione di JoinNode:

cd ~/adk-graph-agents
adk web --allow_origins "*"

Apri l'anteprima web sulla porta 8000, fai clic su + Nuova sessione e invia:

Help me plan a trip to Kyoto focused on historic temples and ramen

Nella visualizzazione Eventi, dovresti vedere una sequenza di eventi simile alla seguente:

1. user_profiler_agent -> emits JSON preferences via node_input
2. activity_finder_agent & restaurant_finder_agent -> invoke google_search concurrently
3. research_join -> merges both researcher outputs into one dict node_input
4. itinerary_synthesizer_agent -> drafts final_itinerary from the merged dict + {user_preferences}

Ispeziona l'esecuzione parallela in adk web: fai clic su Tracce nella parte superiore del riquadro della conversazione (accanto a Eventi) per visualizzare gli intervalli sovrapposti per activity_finder_agent e restaurant_finder_agent oppure fai clic su research_join in Eventi e apri Struttura dell'agente (account_tree nella barra degli strumenti in alto) per ispezionare il grafico fan-out/fan-in a rombo.

Premi Ctrl + C nel terminale per interrompere adk web prima di continuare.

8. Cicli di revisione delle route

Applica i vincoli di budget e negativi aggiungendo un itinerary_critic_agent, un itinerary_refiner_agent e due nodi di funzione Python deterministici (route_critique e finalize_itinerary) che restituiscono oggetti ADK Event:

• route: seleziona la chiave del ramo denominato in un arco dict ({"revise": ..., "approved": ...}) da eseguire successivamente.
• output: passa un valore o una stringa Python tipizzati lungo l'edge come node_input al nodo successivo senza eseguire il rendering di un messaggio di chat.
• message e state: message genera testo visibile all'utente nella trascrizione della chat, mentre state esegue il commit degli aggiornamenti coppia chiave-valore (stateDelta) allo stato della sessione.

Aggiungi gli specialisti di critica e perfezionamento

Verifica che adk web sia stato arrestato (Ctrl + C), quindi apri travel_planner/specialists.py:

cloudshell edit ~/adk-graph-agents/travel_planner/specialists.py

Aggiungi itinerary_critic_agent e itinerary_refiner_agent alla fine di travel_planner/specialists.py (il perfezionatore non ha bisogno di strumenti google_search o exit_loop perché scambia elementi già raccolti in {final_itinerary} e viene eseguito solo quando route_critique seleziona "revise"):

# --- Specialist 5: The Budget & Constraint Critic ---
itinerary_critic_agent = Agent(
    model=MODEL,
    name="itinerary_critic_agent",
    description="Audits the itinerary draft against budget and negative constraints.",
    instruction="""
        Audit the itinerary in the input against User Preferences ({user_preferences}).
        Verify that the USD total stays within the user's budget and no excluded venue types appear.
        If all checks pass, respond EXACTLY with the single word "APPROVED".
        Otherwise, output 1-2 concise revision instructions explaining what to swap or adjust.
    """,
)

# --- Specialist 6: The Itinerary Refiner ---
itinerary_refiner_agent = Agent(
    model=MODEL,
    name="itinerary_refiner_agent",
    description="Revises the itinerary draft using the critic's feedback.",
    instruction="""
        Revise Current Itinerary ({final_itinerary}) using the auditor critique in the input
        so all USD budget and exclusion rules in {user_preferences} pass.
        Output ONLY the updated Markdown itinerary.
    """,
    output_key="final_itinerary",
)

Aggiungi route_critique e il ciclo

Apri travel_planner/workflows.py:

cloudshell edit ~/adk-graph-agents/travel_planner/workflows.py

Sostituisci l'intero contenuto di travel_planner/workflows.py con il workflow del grafo completo:

from google.adk import Event, Workflow
from google.adk.workflow import JoinNode
from .specialists import (
    activity_finder_agent, itinerary_critic_agent, itinerary_refiner_agent,
    itinerary_synthesizer_agent, restaurant_finder_agent, user_profiler_agent,
)

MAX_REVISIONS = 2
research_join = JoinNode(name="research_join")


def route_critique(node_input: str, revision_count: int = 0):
    """Routes to 'approved' when constraints pass, or 'revise' up to MAX_REVISIONS."""
    approved = node_input.strip().rstrip(".").upper() == "APPROVED"
    if approved or revision_count >= MAX_REVISIONS:
        return Event(route="approved", output=approved)
    return Event(
        route="revise", output=node_input, state={"revision_count": revision_count + 1}
    )


def finalize_itinerary(node_input: bool, final_itinerary: str, revision_count: int = 0):
    """Emits the verified itinerary and resets revision_count for the next turn."""
    status = (
        f"Itinerary approved after {revision_count} revision(s)."
        if node_input
        else f"Max revisions ({revision_count}) reached; returning best-effort draft."
    )
    return Event(
        message=f"{status}\n\n{final_itinerary}",
        output=final_itinerary,
        state={"revision_count": 0},
    )


travel_workflow = Workflow(
    name="travel_workflow",
    description="Orchestrates the end-to-end travel planning process as a graph workflow.",
    edges=[
        (
            "START",
            user_profiler_agent,
            (activity_finder_agent, restaurant_finder_agent),
            research_join,
            itinerary_synthesizer_agent,
            itinerary_critic_agent,
            route_critique,
        ),
        (route_critique, {"revise": itinerary_refiner_agent, "approved": finalize_itinerary}),
        (itinerary_refiner_agent, itinerary_critic_agent),
    ],
)

Parametri delle funzioni associati allo stato: ADK 2 associa automaticamente node_input all'output del predecessore e risolve altri nomi di parametri (final_itinerary, revision_count: int = 0) direttamente dallo stato della sessione senza codice boilerplate ctx.state. La reimpostazione di state={"revision_count": 0} all'interno di finalize_itinerary garantisce che i turni successivi nella stessa sessione di chat inizino con un nuovo budget di revisione.

🔍 Controlla il tuo lavoro

Verifica che travel_planner/workflows.py venga compilato correttamente e stampi i bordi del grafo orientato:

cd ~/adk-graph-agents && source .venv/bin/activate
python3 -c "from travel_planner.agent import root_agent; print('\n'.join(f'{e.from_node.name} -> {e.to_node.name} (route={e.route})' for e in root_agent.graph.edges))"

Dovresti visualizzare un output simile al seguente:

__START__ -> user_profiler_agent (route=None)
user_profiler_agent -> activity_finder_agent (route=None)
user_profiler_agent -> restaurant_finder_agent (route=None)
activity_finder_agent -> research_join (route=None)
restaurant_finder_agent -> research_join (route=None)
research_join -> itinerary_synthesizer_agent (route=None)
itinerary_synthesizer_agent -> itinerary_critic_agent (route=None)
itinerary_critic_agent -> route_critique (route=None)
route_critique -> itinerary_refiner_agent (route=revise)
route_critique -> finalize_itinerary (route=approved)
itinerary_refiner_agent -> itinerary_critic_agent (route=None)

Poi, avvia adk web per testare sia l'approvazione immediata sia le revisioni attivate dal budget:

adk web --allow_origins "*"

Apri l'anteprima web sulla porta 8000, fai clic su + Nuova sessione e invia il prompt su Kyoto con più vincoli:

Design a full-day itinerary for Kyoto with a total budget of $100. My main interests are historical landmarks, temples, and authentic local cuisine. Please do not include any modern art museums or galleries.

Per vedere il loop route="revise" in azione, invia un prompt di follow-up con un budget limitato di 15 $:

Now design a full-day Kyoto itinerary with paid temple admissions, lunch, and dinner on a strict total budget of $15 USD.

Nella visualizzazione Eventi, dovresti vedere una sequenza di esecuzione simile a:

1. user_profiler_agent -> writes JSON constraints to state["user_preferences"]
2. (activity_finder_agent, restaurant_finder_agent) -> run google_search concurrently -> research_join
3. itinerary_synthesizer_agent -> writes initial draft to state["final_itinerary"]
4. itinerary_critic_agent -> outputs "APPROVED" (or revision instructions when over budget)
5. route_critique -> emits route="approved" (skipping refiner) or route="revise" -> itinerary_refiner_agent -> itinerary_critic_agent
6. finalize_itinerary -> emits "Itinerary approved after N revision(s)." (or max-revisions notice) and resets revision_count=0

Ispeziona la convalida e il routing del ciclo: fai clic sull'evento route_critique in Eventi per ispezionare actions.route ("approved" o "revise") e actions.stateDelta nella scheda Informazioni oppure fai clic sull'icona account_tree nella barra degli strumenti in alto per visualizzare il grafico compilato. ADK convalida al momento della creazione del grafico che ogni ciclo contenga almeno un arco indirizzato, in modo che non sia possibile compilare un loop infinito incondizionato.

Premi Ctrl + C nel terminale per interrompere adk web.

9. Risoluzione dei problemi

Il menu a discesa degli agenti è vuoto in adk web

• Causa: adk web è stato avviato all'interno di travel_planner/ anziché della directory principale ~/adk-graph-agents oppure la sessione di Cloud Shell è stata riavviata.
• Correzione: premi Ctrl + C, torna alla directory principale e riavvia con cd ~/adk-graph-agents && source .venv/bin/activate && adk web --allow_origins "*".

Errore del modello 404 NOT_FOUND

• Causa: hai premuto Invio per accettare la regione us-central1 predefinita durante adk create anziché digitare global.
• Correzione: apri ~/adk-graph-agents/travel_planner/.env e assicurati che GOOGLE_CLOUD_LOCATION=global sia impostato.

ERROR: [Errno 98] address already in use sulla porta 8000

• Causa: un server adk web precedente è ancora in esecuzione in Cloud Shell.
• Correzione: premi Ctrl + C nel terminale attivo o interrompi il processo esistente con pkill -f "adk web" prima di riavviare adk web.

10. Esegui la pulizia

Rimuovi lo spazio di lavoro locale e, facoltativamente, disabilita l'API o elimina un progetto di workshop dedicato.

Vuoi continuare a sperimentare? Se vuoi continuare a esplorare questo progetto, interrompi adk web (Ctrl + C) e salta i passaggi di eliminazione riportati di seguito.

Elimina i file di progetto locali

Rimuovi la directory ~/adk-graph-agents e l'ambiente virtuale:

cd ~
rm -rf ~/adk-graph-agents

(Facoltativo) Disabilita l'API Agent Platform

Disattiva l'API Agent Platform se non ne hai più bisogno in questo progetto:

gcloud services disable aiplatform.googleapis.com --quiet

⚠️ Eliminazione facoltativa del progetto: elimina il progetto Google Cloud solo se ne hai creato uno dedicato esclusivamente a questo codelab. Eliminalo in Gestisci risorse o esegui gcloud projects delete "$(gcloud config get-value project)" e conferma quando richiesto.

🔍 Controlla il tuo lavoro

Verifica che ~/adk-graph-agents sia stato rimosso:

test ! -d ~/adk-graph-agents && echo "Workspace ~/adk-graph-agents removed"

Dovresti visualizzare un output simile al seguente:

Workspace ~/adk-graph-agents removed

11. Complimenti

Hai creato un pianificatore di viaggi multi-agente utilizzando ADK 2 Workflow, unificando catene sequenziali, fan-out google_search simultaneo con JoinNode e cicli maker-checker condizionali in un unico grafico perimetrale dichiarativo.

Risultati ottenuti

• Dichiarato una pipeline multi-agente utilizzando ADK 2 Workflow(edges=[...])
• Passaggio di dati direttamente tra i nodi delle funzioni Agent, JoinNode e Python tramite node_input e parametri associati allo stato, mantenendo al minimo lo stato della sessione
• Branch google_search simultanei distribuiti e sincronizzati con JoinNode
• Sostituzione di LoopAgent e dell'escalation del loop basata su strumenti con un router Event(route=...) deterministico che salta le chiamate LLM non necessarie sulle bozze approvate

Passaggi successivi

• Esplora i sistemi multi-agente in ADK
• Partecipa al programma GEAR (Gemini Enterprise Agent Ready) e al programma Get Certified per workshop pratici e percorsi di apprendimento