Como criar agentes de IA com o ADK: como orquestrar Agentic Workflows

1. Visão geral

Atender a uma solicitação de viagem com várias restrições (como criar um itinerário de um dia inteiro em Kyoto por menos de US $100, focado em templos históricos e culinária local, sem galerias de arte moderna) requer extrair restrições, pesquisar atrações e restaurantes simultaneamente, montar um cronograma detalhado e auditar o plano final. Depender de um único agente monolítico com muitas ferramentas pode pular etapas de verificação ou violar exclusões. Por isso, a orquestração coordena subagentes especializados usando controladores de fluxo de trabalho determinísticos.

Nesta terceira parte da série Como criar agentes de IA com o ADK, você vai criar um planejador de viagens multiagente independente na Agent Platform usando os controladores de fluxo de trabalho do Kit de Desenvolvimento de Agente (ADK) 2 (SequentialAgent, ParallelAgent e LoopAgent). Em três etapas progressivas (sem a necessidade de configurar o espaço de trabalho da Parte 1 ou 2), você vai coordenar seis agentes especializados com tecnologia do gemini-3.8-flash com estado de sessão compartilhado (output_key), execução simultânea de google_search e um loop de refinamento iterativo de criador-verificador.

Ainda não conhece o ADK? Se você não conhece os conceitos de agentes de IA generativa e o Kit de Desenvolvimento de Agente (ADK) do Google, recomendamos que conclua primeiro os cursos Como criar agentes de IA com o ADK: conceitos básicos e Como criar agentes de IA com o ADK: capacitação com ferramentas.

Quer conhecer os fluxos de trabalho de gráfico do ADK 2? Depois de concluir este codelab, continue para a Parte 4, Como criar agentes de IA com o ADK: como orquestrar fluxos de trabalho de gráfico, para unificar a orquestração sequencial, paralela (JoinNode) e cíclica (Event(route=...)) em um único gráfico declarativo Workflow.

Pré-requisitos

• Noções básicas sobre conceitos de IA generativa
• Proficiência básica em programação Python
• Familiaridade com os conceitos básicos de agentes de IA e o ADK do Google

Conteúdo do laboratório

• Como criar um projeto multiagente do ADK 2 do zero
• Como projetar uma equipe de agentes especializados que compartilham o estado da sessão usando output_key
• Como usar o SequentialAgent para executar subagentes em um pipeline determinístico e detalhado
• Como usar o ParallelAgent para executar agentes de pesquisa independentes simultaneamente para reduzir a latência
• Como usar o escalonamento de LoopAgent e ToolContext para implementar um loop iterativo de refinamento de criador-verificador
• Como combinar padrões sequenciais, paralelos e de loop em um fluxo de trabalho hierárquico de vários agentes

O que é necessário

• Uma Conta do Google (use uma conta pessoal do @gmail.com se estiver resgatando créditos do workshop)
• Um link de crédito do workshop do seu instrutor (além de uma câmera de smartphone para ler o QR code) ou uma conta do Cloud Billing ativa.
• Google Chrome (recomendamos usar uma janela anônima para evitar misturar contas pessoais e de trabalho)

Dica de navegação anônima: abra este codelab em uma janela anônima para que todos os links do console do Cloud e do Cloud Shell sejam abertos na mesma sessão.

2. Resgatar créditos do Google Cloud (opcional)

Se você estiver participando de um workshop com um link de crédito de evento, resgate seu crédito do Google Developer Program para provisionar uma conta de faturamento sem cartão de crédito.

Usando sua própria conta de faturamento? Pule para Criar um projeto na nuvem do Google (opcional) ou Configurar o ambiente se você já tiver um projeto. Se você precisar de uma nova conta de faturamento sem créditos de evento, consulte Criar uma conta do Cloud Billing ou Teste sem custo financeiro do Google Cloud.

Resgatar seu crédito do evento

⚠️ Use uma conta pessoal do Gmail: contas corporativas ou escolares do Google Workspace não podem resgatar créditos de eventos de workshop.

1. Abra o link de crédito do workshop em uma janela anônima e faça login com sua conta do @gmail.com.
2. Em Resgatar seu benefício, clique em Resgatar crédito:

3. Se for solicitado que você crie um perfil do Google Developer Program, preencha o formulário.
4. Quando a mensagem Leia o QR code para confirmar que você é uma pessoa aparecer, leia o QR code com seu smartphone e conclua a verificação. Se o QR code não aparecer, atualize a página e clique em Resgatar crédito novamente:

5. Confirme se a mensagem Seu crédito do evento foi solicitado! aparece e clique em Abrir conta de faturamento:

🔍 Verifique seu trabalho

A configuração da conta de faturamento leva até 3 minutos:

1. Abra o Google Cloud Billing (ou copie o URL na janela anônima) e selecione Suas contas de faturamento:

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

2. Atualize até que sua conta do GDP Credit mostre o status Ativo:

3. Criar um projeto do Google Cloud (opcional)

Crie um projeto dedicado do Google Cloud para que todos os recursos deste codelab fiquem isolados e sejam fáceis de limpar.

Já tem um projeto? Se você já tiver um projeto com faturamento ativado ou um projeto de workshop pré-provisionado, pule para Configurar o ambiente.

1. Abra Criar um projeto (ou copie o URL na janela anônima):

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

2. Insira os detalhes do projeto:
   • Nome do projeto: por exemplo, google-cloud-workshop
   • Conta de faturamento (se exibida): selecione GDP Credit (ou sua conta de faturamento ativa).
   • Recurso pai: Nenhuma organização (ou sua organização, se necessário)
3. Anote o ID do projeto gerado abaixo do nome do projeto e clique em Criar:

🔍 Verifique seu trabalho

Clique em Notificações na barra de ferramentas no canto superior direito e em Selecionar projeto quando a criação do projeto for concluída:

4. Configurar o ambiente

Configurar o Google Cloud Shell, ativar a API Agent Platform e criar um ambiente virtual isolado do Python 3.12 com uv.

Está continuando dos laboratórios 1 e 2? (Fast-Track): se o ID do projeto do Google Cloud e a API Agent Platform já estiverem configurados nesta sessão do Cloud Shell, pule para Criar um ambiente virtual do Python e instalar o ADK para que ~/adk-agents/.venv seja criado sem problemas.

Dica para o terminal local: está usando uma máquina local em vez do Cloud Shell? Execute gcloud auth application-default login uma vez, substitua os comandos cloudshell edit filename pelo seu editor preferido (por exemplo, code filename ou nano filename) e abra http://localhost:8000 diretamente no navegador.

Configure o Cloud Shell

1. Clique em Ativar o Cloud Shell (>_) na barra de ferramentas do console do Google Cloud ou abra o Google Cloud Shell diretamente (ou copie o URL na janela anônima):

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

2. Clique em Autorizar se solicitado:

3. Selecione o ID do projeto ativo do Google Cloud no menu numerado do terminal:

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

Você verá uma saída semelhante a esta (os projetos sem tags também mostram uma linha informativa [environment: untagged]):

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

Verifique se o ID do projeto selecionado aparece destacado em amarelo no prompt do Cloud Shell:

Ativar APIs obrigatórias

Ative a API Agent Platform para que seus agentes do ADK possam invocar modelos do Gemini:

gcloud services enable aiplatform.googleapis.com

Você verá uma saída como:

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

Criar um ambiente virtual do Python e instalar o ADK

Por que uv? Escrito em Rust, o uv cria ambientes Python e instala pacotes em segundos. Saiba mais na documentação do uv.

Crie o espaço de trabalho ~/adk-agents e ative um ambiente virtual do Python 3.12:

cd ~
mkdir -p adk-agents && cd ~/adk-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

Confirme se o prefixo (.venv) aparece no início do prompt do terminal:

Instale o ADK 2 no ambiente virtual ativo:

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

🔍 Verifique seu trabalho

Verifique a versão instalada da CLI adk:

adk --version

Você verá uma saída como:

adk, version 2.14.0

Dica de recuperação de sessão: se a guia do Cloud Shell for desconectada ou se você abrir um novo terminal mais tarde, volte ao espaço de trabalho e reative o ambiente virtual executando cd ~/adk-agents && source .venv/bin/activate.

5. Criar o agente de planejamento de viagens

Com o ambiente pronto, use o comando adk create integrado do ADK para gerar os arquivos iniciais do pacote do agente travel_planner.

Gerar o pacote inicial

Execute adk create no diretório ~/adk-agents:

cd ~/adk-agents
adk create travel_planner

Quando solicitado no terminal, selecione as seguintes opções de configuração (se Enable telemetry? [Y/n]: aparecer na primeira execução, pressione Enter ou digite n e pressione Enter):

1. Escolha um modelo para o agente raiz: digite 2 para selecionar gemini-3.8-flash (a opção 1 seleciona gemini-3.5-flash) e pressione Enter.
2. Escolha um back-end: digite 2 para selecionar o back-end da Plataforma de Agentes do Google Cloud (opção 2 no menu da CLI abaixo) e pressione Enter.
3. Insira o ID do projeto do Google Cloud: confirme o ID do projeto mostrado entre colchetes pressionando Enter.
4. Insira a região do Google Cloud: digite global e pressione Enter.

O adk create grava GOOGLE_GENAI_USE_ENTERPRISE=1, o ID do projeto e GOOGLE_CLOUD_LOCATION=global em travel_planner/.env para que suas credenciais permaneçam configuradas quando você atualizar o agent.py mais tarde.

🔍 Verifique seu trabalho

Você verá uma saída como:

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-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/)

Abra a pasta atual no editor de código do Cloud Shell para inspecionar e editar arquivos lado a lado com o terminal:

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

Observação sobre a reinicialização do terminal: a execução de cloudshell workspace recarrega a visualização de edição do Cloud Shell. Depois que o painel do terminal for recarregado, reative o ambiente virtual antes de continuar:

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

Testar o agente único padrão

Antes de criar Agentic Workflows multiagente, inicie a interface de desenvolvimento do ADK para observar como o agente único padrão responde a uma consulta ampla de planejamento de viagem:

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

Abra a interface de desenvolvimento no navegador usando a Visualização da Web do Cloud Shell:

1. Clique no ícone Visualização da Web na barra de ferramentas no canto superior direito do Cloud Shell.
2. Selecione Alterar porta, insira 8000 e clique em Alterar e visualizar.

Depois que a interface da Web do ADK for carregada, envie uma saudação, como "hello, what can you do?" ou "Help me plan a trip to Japan":

Observe que o root_agent único responde diretamente em uma única passagem, sem extração estruturada de preferências, pesquisa ao vivo na Web ou verificação de orçamento.

Quando terminar o teste, pressione Ctrl + C no terminal do Cloud Shell para interromper o servidor adk web e voltar ao prompt de comando.

6. Criar um fluxo de trabalho SequentialAgent

Agora você vai criar seu primeiro padrão de orquestração: um fluxo de trabalho linear com tecnologia do SequentialAgent. Em um pipeline sequencial, os subagentes são executados em uma ordem estrita. O primeiro especialista extrai parâmetros estruturados e os salva no estado da sessão compartilhada usando output_key="user_preferences", e o segundo especialista lê {user_preferences} do estado compartilhado para elaborar o itinerário.

Criar os especialistas iniciais (specialists.py)

Abra um novo arquivo chamado specialists.py em travel_planner/:

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

Cole o código a seguir em travel_planner/specialists.py para definir user_profiler_agent e itinerary_synthesizer_agent (importando ToolContext e google_search com antecedência para as próximas etapas):

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

# --- Specialist 1: The User Profiler ---
user_profiler_agent = Agent(
    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",  # Saves output to state['user_preferences']
)

# --- Specialist 2: The Synthesizer ---
itinerary_synthesizer_agent = Agent(
    name="itinerary_synthesizer_agent",
    description="Compiles preferences and research into a final Markdown itinerary.",
    instruction="""
        You are an elite Travel Concierge. Write a Markdown itinerary with an itemized USD and local currency cost breakdown using:
        - User Preferences: {user_preferences}
        - Activities (if available): {activity_recommendations?}
        - Restaurants (if available): {restaurant_recommendations?}
    """,
    output_key="final_itinerary",
)

Herança de modelo e transmissão de estado no ADK: os subagentes em SequentialAgent, ParallelAgent e LoopAgent herdam automaticamente o model configurado em root_agent em agent.py (gemini-3.8-flash). Assim, você define MODEL em um só lugar, em vez de repetir model= em cada especialista. Definir output_key="user_preferences" em user_profiler_agent armazena a resposta em session.state["user_preferences"], que os agentes seguintes injetam com {user_preferences} (um ? final, como {activity_recommendations?}, marca um marcador de posição de estado como opcional até que seja preenchido).

Conectar o pipeline sequencial (workflows.py)

Crie um novo arquivo chamado workflows.py em travel_planner/ para orquestrar os especialistas:

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

Adicione a seguinte definição de SequentialAgent a travel_planner/workflows.py:

from google.adk.agents import SequentialAgent
from .specialists import (
    user_profiler_agent,
    itinerary_synthesizer_agent,
)

# 1. SEQUENTIAL PHASE: A linear two-step workflow
master_travel_agent = SequentialAgent(
    name="master_travel_agent",
    description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
    sub_agents=[
        user_profiler_agent,         # Step 1: Extract constraints into user_preferences
        itinerary_synthesizer_agent,  # Step 2: Draft itinerary from user_preferences
    ],
)

Conectar o fluxo de trabalho ao root_agent (agent.py)

Agora registre master_travel_agent como um subagente de root_agent. Abra travel_planner/agent.py:

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

Substitua o conteúdo de travel_planner/agent.py pelo seguinte código:

from google.adk import Agent
from .workflows import master_travel_agent

MODEL = "gemini-3.8-flash"

root_agent = Agent(
    model=MODEL,
    name="root_agent",
    description="A helpful assistant for user questions.",
    instruction=(
        "Greet the user and delegate any travel or trip planning requests "
        "to master_travel_agent."
    ),
    sub_agents=[master_travel_agent],
)

🔍 Verifique seu trabalho

Inicie a interface da Web do ADK no terminal:

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

Abra a Visualização da Web na porta 8000 e insira o comando:

Help me plan a trip to Kyoto

Você verá uma saída semelhante ao seguinte fluxo de execução na visualização Eventos:

1. root_agent -> calls transfer_to_agent(agent_name="master_travel_agent")
2. user_profiler_agent -> outputs JSON {"destination": "Kyoto", "duration": "1 day", ...} to state['user_preferences']
3. itinerary_synthesizer_agent -> reads {user_preferences} and outputs the formatted Markdown itinerary

Clique em qualquer selo de evento (ou no ícone State: final_itinerary) e mude para a guia Estado no painel de inspeção à esquerda para confirmar que user_preferences e final_itinerary estão preenchidos no estado da sessão.

Quando terminar de inspecionar o trace, pressione Ctrl + C no terminal para interromper o adk web.

7. Fazer pesquisas com o ParallelAgent

Embora o fluxo de trabalho sequencial separe claramente a extração de preferências da elaboração do itinerário, as recomendações ainda dependem puramente do conhecimento de treinamento estático do modelo. Você pode embasar o itinerário em dados da Web em tempo real adicionando dois pesquisadores dedicados com a ferramenta google_search integrada:

• activity_finder_agent: encontra três atrações específicas que correspondem ao destino e aos interesses do usuário, além de estimar os preços dos ingressos.
• restaurant_finder_agent: encontra três restaurantes locais bem avaliados e o custo estimado por pessoa.

Como a pesquisa de atrações e a de restaurantes não dependem uma da outra, executá-las uma após a outra é uma perda de tempo. Em vez disso, você vai encapsular os dois pesquisadores em um ParallelAgent (parallel_research_agent) para que o ADK execute os dois fluxos de trabalho da Pesquisa Google simultaneamente e preencha {activity_recommendations?} e {restaurant_recommendations?} antes de passar para itinerary_synthesizer_agent.

Adicione os especialistas em pesquisa paralela a specialists.py

Abra travel_planner/specialists.py:

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

Adicione os dois especialistas da Pesquisa Google a seguir ao final de travel_planner/specialists.py (logo abaixo de itinerary_synthesizer_agent):

# --- Specialist 3: The Activity Finder ---
activity_finder_agent = Agent(
    name="activity_finder_agent",
    description="Finds 3 attractions matching the user's destination and interests.",
    instruction="""
        Based on {user_preferences}, use 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],
    output_key="activity_recommendations",
)

# --- Specialist 4: The Restaurant Finder ---
restaurant_finder_agent = Agent(
    name="restaurant_finder_agent",
    description="Finds 3 restaurants matching the destination and budget.",
    instruction="""
        Based on {user_preferences}, use 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],
    output_key="restaurant_recommendations",
)

Bônus: trazer de volta get_fx_rate do Laboratório 2 (opcional): em Como criar agentes de IA com o ADK: capacitação com ferramentas, você escreveu uma função get_fx_rate(base: str, target: str) simples em Python para buscar taxas de câmbio em tempo real de https://hexarate.paikama.co/api/rates/latest. Ao manter google_search isolado nos dois especialistas em pesquisa (activity_finder_agent e restaurant_finder_agent) e anexar tools=[get_fx_rate] diretamente a itinerary_synthesizer_agent, cada agente se concentra em um único trabalho. Além disso, a divisão permanece portátil mesmo em modelos mais antigos do Gemini, enquanto os modelos Gemini 3+ também oferecem suporte à combinação de ferramentas integradas, como google_search, com funções personalizadas em um único agente.

Insira ParallelAgent em workflows.py

Abra travel_planner/workflows.py:

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

Atualize travel_planner/workflows.py para definir parallel_research_agent usando ParallelAgent e coloque-o entre user_profiler_agent e itinerary_synthesizer_agent:

from google.adk.agents import ParallelAgent, SequentialAgent
from .specialists import (
    activity_finder_agent,
    itinerary_synthesizer_agent,
    restaurant_finder_agent,
    user_profiler_agent,
)

# Parallel branch: Run activity and restaurant research simultaneously
parallel_research_agent = ParallelAgent(
    name="parallel_research_agent",
    description="Runs activity and restaurant research concurrently.",
    sub_agents=[
        activity_finder_agent,
        restaurant_finder_agent,
    ],
)

# Master pipeline: Profile -> Parallel Research -> Synthesize
master_travel_agent = SequentialAgent(
    name="master_travel_agent",
    description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
    sub_agents=[
        user_profiler_agent,          # Step 1: Extract constraints
        parallel_research_agent,      # Step 2: Research activities & restaurants in parallel
        itinerary_synthesizer_agent,  # Step 3: Synthesize into an itinerary
    ],
)

🔍 Verifique seu trabalho

Inicie o adk web novamente para testar o pipeline de pesquisa paralela:

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

Na interface de visualização da Web, envie o comando:

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

Você verá uma saída semelhante à seguinte sequência na visualização Eventos:

1. user_profiler_agent -> writes state['user_preferences']
2. parallel_research_agent -> fans out concurrently:
   - activity_finder_agent invokes google_search -> writes state['activity_recommendations']
   - restaurant_finder_agent invokes google_search -> writes state['restaurant_recommendations']
3. itinerary_synthesizer_agent -> merges all three state keys into state['final_itinerary']

Como inspecionar a simultaneidade na interface da Web do ADK: alterne entre essas visualizações na interface da Web do ADK para verificar a execução paralela:

1. Visualização de traces: clique em Traces na parte de cima do painel de conversa (ao lado de Eventos) e inspecione sua vez. Você vai notar períodos de linha do tempo sobrepostos para activity_finder_agent e restaurant_finder_agent em parallel_research_agent, o que reduz a latência total da pesquisa na Web quase pela metade em comparação com a execução sequencial.
2. Guia "State": clique na guia State no painel de inspeção à esquerda para inspecionar o dicionário da sessão ativa (user_preferences, activity_recommendations, restaurant_recommendations e final_itinerary).

Quando terminar o teste, pressione Ctrl + C no terminal para interromper o adk web.

8. Refinar rascunhos com o LoopAgent

Mesmo com os resultados da Pesquisa Live, o rascunho inicial produzido pelo itinerary_synthesizer_agent pode exceder o orçamento total do usuário ou incluir acidentalmente uma categoria excluída (como uma galeria de arte moderna quando o usuário pediu para não incluir nenhuma).

Para garantir a conformidade com as restrições, adicione um loop de refinamento de criador-verificador ao final do pipeline usando LoopAgent:

1. itinerary_critic_agent (o verificador): audita {final_itinerary} em relação a {user_preferences}. Ele soma os custos estimados, verifica todas as restrições negativas e escreve instruções de revisão específicas para critique_feedback ou responde com a frase exata "APPROVED".
2. itinerary_refiner_agent (criador/saída): lê {critique_feedback}. Se a crítica for igual a "APPROVED", ela vai invocar a ferramenta exit_loop (tool_context.actions.escalate = True) para sair do LoopAgent imediatamente. Caso contrário, ele revisa {final_itinerary} para corrigir os problemas sinalizados e substitui final_itinerary para a próxima passagem.

Anexar exit_loop, Critic e Refiner a specialists.py

Abra travel_planner/specialists.py:

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

Anexe a ferramenta exit_loop (ToolContext), itinerary_critic_agent e itinerary_refiner_agent à parte de baixo de travel_planner/specialists.py:

def exit_loop(tool_context: ToolContext) -> dict:
    """Call ONLY when the critique is APPROVED to exit the refinement loop."""
    print(f"[Tool Call] exit_loop triggered by {tool_context.agent_name}")
    tool_context.actions.escalate = True
    return {"status": "approved", "message": "Itinerary approved. Exiting refinement loop."}


# --- Specialist 5: The Budget & Constraint Critic (Inside LoopAgent) ---
itinerary_critic_agent = Agent(
    name="itinerary_critic_agent",
    include_contents="none",
    description="Audits the itinerary draft against budget and negative constraints.",
    instruction="""
        Audit Current Itinerary ({final_itinerary}) 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.
    """,
    output_key="critique_feedback",
)

# --- Specialist 6: The Itinerary Refiner / Exiter (Inside LoopAgent) ---
itinerary_refiner_agent = Agent(
    name="itinerary_refiner_agent",
    include_contents="none",
    description="Refines the itinerary from critique feedback, or calls exit_loop when APPROVED.",
    instruction="""
        Review Auditor Critique ({critique_feedback}) for Current Itinerary ({final_itinerary}).
        If the critique is EXACTLY "APPROVED", call `exit_loop` immediately and return the itinerary unchanged.
        Otherwise, revise the draft using {activity_recommendations} and {restaurant_recommendations}
        so all USD budget and exclusion rules pass, and output ONLY the updated Markdown itinerary.
    """,
    tools=[exit_loop],
    output_key="final_itinerary",
)

Atalho exit_loop integrado no ADK: ao escrever exit_loop(tool_context: ToolContext), você pode registrar a chamada de ferramenta e ver como tool_context.actions.escalate = True sinaliza para LoopAgent parar. Em projetos de produção, também é possível importar o assistente integrado do ADK diretamente pelo from google.adk.tools import exit_loop, que define tool_context.actions.escalate = True e tool_context.actions.skip_summarization = True para você.

Adição de LoopAgent à workflows.py.

Abra travel_planner/workflows.py:

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

Atualize travel_planner/workflows.py para unir itinerary_critic_agent e itinerary_refiner_agent em um LoopAgent (max_iterations=3) e adicione-o como a quarta etapa de master_travel_agent:

from google.adk.agents import LoopAgent, ParallelAgent, SequentialAgent
from .specialists import (
    activity_finder_agent,
    itinerary_critic_agent,
    itinerary_refiner_agent,
    itinerary_synthesizer_agent,
    restaurant_finder_agent,
    user_profiler_agent,
)

# Stage 2: Parallel research branch
parallel_research_agent = ParallelAgent(
    name="parallel_research_agent",
    description="Runs activity and restaurant research concurrently.",
    sub_agents=[
        activity_finder_agent,
        restaurant_finder_agent,
    ],
)

# Stage 4: Iterative Maker-Checker refinement loop
refinement_loop_agent = LoopAgent(
    name="refinement_loop_agent",
    description="Iteratively audits and refines the itinerary until constraints and budget are approved.",
    sub_agents=[
        itinerary_critic_agent,
        itinerary_refiner_agent,
    ],
    max_iterations=3,
)

# Master pipeline: Profile -> Parallel Research -> Synthesize -> Refinement Loop
master_travel_agent = SequentialAgent(
    name="master_travel_agent",
    description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
    sub_agents=[
        user_profiler_agent,          # Stage 1: Extract constraints
        parallel_research_agent,      # Stage 2: Research activities & restaurants in parallel
        itinerary_synthesizer_agent,  # Stage 3: Draft initial itinerary
        refinement_loop_agent,        # Stage 4: Audit and refine until approved
    ],
)

🔍 Verifique seu trabalho

Inicie o adk web para testar o fluxo de trabalho multiagente completo:

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

Abra a interface da Visualização da Web na porta 8000, inicie uma Nova sessão e teste o sistema completo com este comando de várias restrições de Kyoto:

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.

Você verá uma saída semelhante à seguinte sequência de execução na visualização Eventos e nos registros do terminal:

1. user_profiler_agent -> writes JSON with destination="Kyoto", budget="$100", exclusions=["modern art museums", "galleries"]
2. parallel_research_agent -> runs activity_finder_agent and restaurant_finder_agent in parallel
3. itinerary_synthesizer_agent -> produces initial draft in state['final_itinerary']
4. refinement_loop_agent:
   - itinerary_critic_agent -> audits USD budget and exclusions -> outputs "APPROVED" (or revision notes)
   - itinerary_refiner_agent -> triggers [Tool Call] exit_loop triggered by itinerary_refiner_agent and outputs the approved itinerary

Como inspecionar as iterações de repetição e o encaminhamento na interface da Web do ADK:

1. Visualização de eventos: clique em qualquer ícone de evento de itinerary_critic_agent ou itinerary_refiner_agent para inspecionar o payload na guia Informações à esquerda. Quando itinerary_refiner_agent invocar exit_loop, inspecione o evento para ver actions.escalate: true, o sinal que informa a LoopAgent para interromper a iteração antes de chegar a max_iterations=3.
2. Guia "State": clique na guia State para ver as atualizações de state['critique_feedback'] e state['final_itinerary'] em todas as passagens. Se o rascunho inicial exceder $100 USD, critique_feedback vai conter as instruções de revisão do auditor na primeira etapa antes que final_itinerary seja atualizado com alternativas de menor custo e critique_feedback mude para "APPROVED" na segunda etapa.

Quando terminar o teste, pressione Ctrl + C no terminal para interromper o adk web.

9. Limpar

Continuar a série? Se você planeja continuar testando seu projeto nos próximos laboratórios, basta interromper o processo adk web em execução com Ctrl + C e pular as etapas de exclusão abaixo.

Excluir os arquivos do projeto local

Para remover o diretório do projeto adk-agents e o ambiente virtual da pasta inicial do Cloud Shell, execute:

cd ~
rm -rf ~/adk-agents

Desativar a API Agent Platform

Se você não precisar mais da API Agent Platform ativada no seu projeto, desative-a com gcloud:

gcloud services disable aiplatform.googleapis.com --quiet

Excluir todo o projeto na nuvem do Google Cloud (opcional)

⚠️ Ação destrutiva: só exclua o projeto na nuvem do Google Cloud se você tiver criado um projeto dedicado exclusivamente para este codelab. A exclusão de um projeto remove permanentemente todos os recursos dele e não pode ser desfeita.

PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete "$PROJECT_ID" --quiet

🔍 Verifique seu trabalho

Confirme se ~/adk-agents foi removido:

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

Você verá uma saída como:

Workspace ~/adk-agents removed

10. Parabéns

Parabéns! Você criou um sistema multiagente hierárquico com o Kit de Desenvolvimento de Agente (ADK) do Google que coordena uma equipe de seis agentes especializados em fluxos de trabalho sequenciais, paralelos e de loop iterativo.

O que você fez até aqui

• Comunicação estruturada entre agentes por meio de estado de sessão compartilhado (injeção de modelo output_key e {state_variable})
• Criou um pipeline determinista detalhado usando o SequentialAgent
• Executou agentes de pesquisa independentes da Pesquisa Google simultaneamente usando ParallelAgent
• Implementação de um loop de verificação automatizado de criador-verificador usando LoopAgent e tool_context.actions.escalate = True

Próximas etapas

• Continue para a Parte 4 da série, Como criar agentes de IA com o ADK: como orquestrar fluxos de trabalho de gráficos, para recriar esse planejador de viagens com os ciclos unificados Workflow, JoinNode e determinísticos Event(route=...) do ADK 2.
• Leia a documentação oficial dos agentes de fluxo de trabalho do ADK.
• Conheça os sistemas multiagentes no ADK
• Participe dos programas GEAR (Gemini Enterprise Agent Ready) e Receba sua Certificação para ter acesso a workshops práticos e programas de aprendizado