Criar um sommelier de durião multimodal com o ADK e o Antigravity

1. Visão geral

Escolher um bom durião em uma barraca de rua é um quebra-cabeça sensorial. Os compradores precisam distinguir um Musang King (D197) genuíno de um parecido, julgar se a fruta caiu esta manhã ou há dias e adivinhar se vão gostar do sabor.

Neste codelab, você vai criar e testar um sistema multiagente multimodal de Sommelier de Durian com o Kit de Desenvolvimento de Agente (ADK) e a Agents CLI. Se quiser, você também poderá implantá-lo no Cloud Run com a CLI do Antigravity (as etapas principais levam cerca de 45 minutos, e as duas etapas opcionais do Antigravity adicionam cerca de 20 minutos). Escolher um durião mostra onde termina a percepção da IA e onde começam os sentidos humanos:

  • O que a IA pode ver: o Gemini pode analisar uma foto da casca e identificar marcadores de cultivo, como a estrela de cinco pontas na base de um Musang King, a ponta escura e afundada de um Black Thorn (D200), o anel do tamanho de uma moeda de um D24 ou um caule seco e murcho.
  • O que só um humano pode sentir: um modelo não pode cheirar a costura para sentir um aroma alcoólico, bater na casca para ouvir um som oco ou pressionar dois espinhos para sentir se eles voltam ao lugar.
  • O que o agente precisa lembrar: dois duriões perfeitamente maduros ainda dividem os compradores. Algumas pessoas adoram o sabor amargo e alcoólico do XO D24 de uma árvore antiga, enquanto outras preferem o creme doce e sem amargor do Red Prawn (D175).

O limite sensorial do durião: visão de IA x sentidos humanos

O que você vai criar

  • Etapa 1: agente de visão única: um agente do ADK, estruturado com a Agents CLI, que identifica o cultivar e o frescor de um durião com base em uma foto.
  • Estágio 2: sentidos humanos e memória do paladar: ferramentas que avaliam o que o comprador cheira, ouve e sente, além de uma ferramenta que salva o perfil de sabor dele em várias sessões.
  • Etapa 3: coordenador e especialistas: um coordenador do durian_advisor que chama um inspetor de visão e um sommelier sensorial e, em seguida, dá um veredito claro.
  • Etapa 4: serviço de agente do Cloud Run: em uma etapa opcional, a CLI do Antigravity implanta seu agente com as habilidades da CLI de agentes.
  • Etapa 5: chatbot da Web do Cloud Run: em outra etapa opcional, a CLI do Antigravity cria e implanta um app de chat compatível com dispositivos móveis que se comunica com seu agente.

Arquitetura

Arquitetura do Sommelier de Durian: um chatbot da Web do Cloud Run chama o coordenador durian_advisor no Cloud Run, que chama especialistas em visão e sensoriais e mantém o paladar do comprador no estado da sessão do ADK

Os dois serviços do Cloud Run vêm das etapas opcionais do Antigravity. Sem eles, você executa os mesmos agentes no ADK Playground no Cloud Shell.

Pré-requisitos

  • Proficiência básica em programação Python
  • Familiaridade com ferramentas de linha de comando e conceitos de IA generativa
  • Não é necessário ter experiência prévia com o ADK, a Agents CLI ou a CLI do Antigravity.

O que você vai aprender

  • Como estruturar um projeto do ADK com agents-cli create e criar um agente multimodal que lê fotos
  • Onde a percepção da IA para (olfato, som, tato e gosto pessoal) e como projetar ferramentas human-in-the-loop para esses sentidos
  • Como lembrar as preferências de cada usuário entre as sessões com o estado do ADK com escopo user:
  • Como dividir um agente em um coordenador e agentes especialistas de turno único que ele chama como ferramentas
  • Opcionalmente, como dar à CLI do Antigravity as habilidades da Agents CLI para que ela possa implantar seu agente e um chatbot da Web no Cloud Run.

O que é necessário

  • Uma Conta do Google (use uma conta pessoal do @gmail.com se estiver reivindicando créditos de 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)

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

Se você estiver fazendo este codelab por conta própria e se qualificar, use o banner de créditos do Google Developer Program nesta página para resgatar créditos sem um cartão de crédito. Se você estiver participando de um workshop com um link de crédito de evento do seu instrutor, siga as etapas de crédito de evento nesta seção.

Resgatar seu crédito do evento

Você resgata créditos de eventos de workshop pelo Google Builders Hub (parte do Google Developer Program).

Para resgatar seu crédito de evento, siga estas etapas:

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

Card "Resgate seu benefício" do Google Builders Hub mostrando o botão "Resgatar crédito".

  1. Opcional: se aparecer uma solicitação para criar um perfil do Google Developer Program, preencha o formulário.
  2. Quando a caixa de diálogo Faça a leitura para confirmar que você é um ser humano 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.
  3. Confirme se a mensagem Seu crédito do evento foi solicitado! aparece e clique em Abrir conta de faturamento.

Card de confirmação do Google Builders Hub mostrando que o crédito do evento foi solicitado e o botão "Abrir conta de faturamento".

🔍 Verifique seu trabalho

O provisionamento da conta de faturamento pode levar até cinco minutos. Para confirmar se o crédito está ativo, siga estas etapas:

  1. Se a página Gerenciamento da conta de faturamento ainda não estiver aberta, acesse o Google Cloud Billing (ou copie o URL na janela anônima):
https://console.cloud.google.com/billing
  1. Clique na guia Suas contas de faturamento e atualize a página até que uma conta com Crédito do GDP mostre Ativa na coluna Status.

Página de gerenciamento de contas do Cloud Billing mostrando uma conta de faturamento ativa com crédito do GDP.

3. Criar um projeto do Google Cloud (opcional)

Crie um projeto na nuvem dedicado do Google Cloud para manter todos os recursos deste codelab isolados e removê-los de forma limpa quando terminar.

Para criar um projeto do Google Cloud, siga estas etapas:

  1. Abra Criar um projeto (ou copie o URL para a janela anônima):
https://console.cloud.google.com/projectcreate
  1. Insira os detalhes do projeto:
    • Nome do projeto: insira um nome descritivo, como google-cloud-workshop.
    • Conta de faturamento (se exibida): selecione sua conta de crédito do GDP (ou sua conta de faturamento ativa).
    • Recurso pai: deixe a opção Sem organização selecionada (ou selecione sua organização, se necessário).
  2. Anote o ID do projeto gerado e clique em Criar.

Formulário "Criar um projeto na nuvem do Google" mostrando o nome do projeto, o ID do projeto gerado, o recurso pai e o botão "Criar".

🔍 Verifique seu trabalho

Depois que o projeto for criado, abra as Notificações na barra de ferramentas do console do Google Cloud e clique em Selecionar projeto.

Menu "Notificações" do console do Google Cloud mostrando o link "Criar projeto" e "Selecionar projeto".

4. Configurar o ambiente

Nesta seção, você vai configurar o Google Cloud Shell, ativar a API Agent Platform e instalar a Agents CLI com uv.

Configure o Cloud Shell

Iniciar o Cloud Shell

Abra o Google Cloud Shell com o editor de código e a visualização do terminal ativados (ou copie o URL para a janela anônima) e clique em Autorizar se solicitado:

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

Caixa de diálogo "Autorizar o Cloud Shell"

Defina o ID do projeto do Google Cloud

Copie e cole o snippet a seguir no terminal do Cloud Shell. Ele exibe um menu numerado dos seus projetos na nuvem disponíveis do Google Cloud. Digite o número ao lado do projeto (por exemplo, 1) e pressione Enter:

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

Comando esperado:

1) durian-sommelier-workshop-4210
2) my-cloud-project-8812
Select your project (e.g. 1): 1
Updated property [core/project].
[environment: untagged] Read more to tag: g.co/cloud/project-env-tag.

Agora, o ID do projeto selecionado vai aparecer em amarelo no prompt do terminal do Cloud Shell:

Terminal do Cloud Shell mostrando o ID do projeto selecionado em destaque em amarelo

ativar a API Agent Platform

Ative a API Agent Platform, que seus agentes usam para chamar o Gemini:

gcloud services enable aiplatform.googleapis.com

🔍 Verifique seu trabalho

Você verá uma saída como:

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

Instalar a Agents CLI

Verifique se o uv está disponível e se a pasta de ferramentas dele está no PATH:

which uv || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

Instale a CLI de agentes como uma ferramenta uv:

uv tool install google-agents-cli==1.7.0

O uv instala cada ferramenta em um ambiente isolado e adiciona apenas o comando agents-cli ao PATH, para que o Python do sistema permaneça intocado. Você também não precisa instalar o ADK. Cada projeto criado pela Agents CLI recebe o próprio ambiente virtual com uma versão do ADK em que o modelo foi testado.

🔍 Verifique seu trabalho

Confirme se a Agents CLI está pronta:

agents-cli --version

Você verá uma saída como:

agents-cli, version 1.7.0

5. Criar um agente de visão multimodal

Comece aos poucos: use a Agents CLI para gerar um projeto do ADK e transforme o agente de amostra em um classificador de visão de durião.

Criar o scaffolding do projeto

Gere o projeto durian-advisor. --agent adk_python escolhe o modelo do ADK para Python, --deployment-target cloud_run e --region us-central1 o preparam para o Cloud Run, --prototype pula a configuração de CI/CD e --yes aceita os padrões:

cd ~ && agents-cli create durian-advisor \
  --agent adk_python \
  --deployment-target cloud_run \
  --region us-central1 \
  --prototype \
  --yes

Você verá uma saída como:

> Verifying GCP credentials...
> ✓ Connected to project: your-project-id

✅ Success! Your agent project is ready.

Abra o projeto no editor do Cloud Shell. Isso recarrega a janela e reinicia o terminal:

cloudshell workspace ~/durian-advisor

Instale as dependências do projeto na própria pasta .venv:

cd ~/durian-advisor && agents-cli install

Verificar o arquivo de ambiente

A CLI de agentes também gravou um arquivo .env que instrui o ADK a chamar o Gemini pelo seu projeto na nuvem do Google Cloud:

grep GOOGLE_ ~/durian-advisor/.env

Você verá uma saída como:

GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

Manter GOOGLE_CLOUD_LOCATION=global. O Gemini 3.8 Flash é disponibilizado no endpoint global, não em endpoints regionais como us-central1, mesmo que os serviços do Cloud Run sejam executados em us-central1.

Se GOOGLE_CLOUD_PROJECT mostrar your-gcp-project-id, a Agents CLI não conseguiu detectar seu projeto. Defina-o com:

sed -i "s/your-gcp-project-id/$(gcloud config get-value project)/" ~/durian-advisor/.env

Escrever o classificador de visão

Cada cultivar tem marcadores de casca que o Gemini pode identificar em uma foto:

Guia visual de cultivares de durião mostrando os marcadores de base e espinho de Musang King, Black Thorn, Red Prawn e D24

Abra app/agent.py:

cloudshell edit ~/durian-advisor/app/agent.py

Substitua o conteúdo dele pelo seguinte código:

"""A single multimodal agent that inspects durian photos."""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

MODEL = "gemini-3.8-flash"

INSTRUCTION = """You are a durian visual classifier. Inspect the durian photo or shell description.
1. Base seam: a 5-point star means Musang King (D197). A dark sunken tip means Black Thorn (D200). A coin-sized brown ring means D24. An oval body with widely spaced, hooked thorns means Red Prawn (D175).
2. Stem: plump, moist, and greenish means it fell within about 12 hours. Dry and shriveled means it is days old.
3. Husk: closed seams mean natural ripening. Wide splits or mold mean it is past its best.
Give the likely cultivar and a visual freshness score from 1 to 10. Then list what a photo cannot tell you: the aroma, the tap sound, the thorn springiness, and whether the buyer will enjoy the taste."""

root_agent = Agent(
    name="durian_advisor",
    model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
    description="Classifies durian cultivars and visual freshness from photos.",
    instruction=INSTRUCTION,
)

app = App(root_agent=root_agent, name="app")

Alguns detalhes são importantes aqui:

  • MODEL é o único lugar em que o ID do modelo aparece. Cada agente adicionado depois herda essa configuração, então mudar de modelo é uma alteração de uma linha.
  • O retry_options tenta corrigir erros temporários, como limites de taxa, até três vezes.
  • app = App(...) envolve o agente para o playground e o servidor do Cloud Run. Mantenha o nome do app app e o nome do agente durian_advisor, que correspondem ao servidor gerado e a agents-cli-manifest.yaml.

Testar o agente no Playground

Inicie o Playground do ADK:

cd ~/durian-advisor && agents-cli playground

Você verá uma saída como:

INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Clique em Visualização da Web na barra de ferramentas do Cloud Shell e selecione Visualizar na porta 8080. Se a interface de desenvolvimento do ADK pedir para você escolher um agente, selecione app. Em seguida, envie este comando ou anexe sua própria foto de durião com o botão de upload:

I'm at a stall looking at a round durian with pyramid-shaped thorns and a 5-point star at the base. The stem is green and moist. What cultivar is this, and will it taste sweet?

🔍 Verifique seu trabalho

O agente identifica o Musang King (D197) e dá uma pontuação alta de frescor para o caule verde úmido. Em seguida, ele admite o que uma foto não pode dizer: o aroma, o som do toque, a elasticidade do espinho e se você vai gostar do sabor.

Pressione Ctrl + C no terminal para interromper o playground antes de continuar.

6. Adicionar sentidos humanos e memória de paladar

Uma câmera não pode cheirar, ouvir ou sentir, então você vai criar ferramentas que pedem ao comprador para fazer isso. Você também vai dar ao agente uma memória de longo prazo do gosto de cada comprador. Nesta etapa, você vai escrever as ferramentas. Na próxima, vai conectá-las aos agentes.

Adicionar o catálogo de cultivares

Crie app/durian_data.py:

cloudshell edit ~/durian-advisor/app/durian_data.py

Cole este catálogo de referência. Manter os dados no próprio módulo deixa o código do agente mais curto:

"""Reference catalog of durian cultivars."""

CULTIVAR_CATALOG = {
    "musang_king": {
        "code": "D197",
        "name": "Musang King (Mao Shan Wang)",
        "visual_markers": "5-point star seam at the base, pyramid-shaped thorns",
        "flavor": "rich, bittersweet, buttery custard",
        "bitterness": "medium",
    },
    "black_thorn": {
        "code": "D200",
        "name": "Black Thorn (Ochee)",
        "visual_markers": "Dark sunken tip at the base, round pumpkin-like body",
        "flavor": "sweet, creamy, slightly winey",
        "bitterness": "low",
    },
    "red_prawn": {
        "code": "D175",
        "name": "Red Prawn (Udang Merah)",
        "visual_markers": "Oval body, widely spaced and slightly hooked thorns",
        "flavor": "sweet, floral, soft and sticky",
        "bitterness": "none",
    },
    "xo_d24": {
        "code": "D24",
        "name": "XO D24 (Sultan, old tree)",
        "visual_markers": "Coin-sized brown ring at the base, dense sharp thorns",
        "flavor": "intense, bitter, with a boozy finish",
        "bitterness": "high",
    },
}

Adicionar as ferramentas sensoriais

Crie app/sensory_tools.py:

cloudshell edit ~/durian-advisor/app/sensory_tools.py

Cole o seguinte código:

"""Tools for cultivar lookup and human-in-the-loop sensory checks."""

from typing import Any, Literal

from .durian_data import CULTIVAR_CATALOG

AROMA_POINTS = {"sweet_fragrant": 4, "boozy_fermented": 3, "faint_grassy": 0, "sour_rotten": 0}
TAP_POINTS = {"hollow": 3, "solid": 0}
THORN_POINTS = {"springy": 3, "rigid": 0}


def get_cultivar_profile(cultivar_key: str) -> dict[str, Any]:
    """Looks up the visual markers, flavor, and bitterness of a durian cultivar.

    Args:
        cultivar_key: One of 'musang_king', 'black_thorn', 'red_prawn', or 'xo_d24'.
    """
    key = cultivar_key.strip().lower().replace(" ", "_").replace("-", "_")
    if key not in CULTIVAR_CATALOG:
        return {"status": "NOT_FOUND", "supported": list(CULTIVAR_CATALOG)}
    return {"status": "OK", "cultivar": CULTIVAR_CATALOG[key]}


def evaluate_human_sensory_clues(
    aroma: Literal["sweet_fragrant", "boozy_fermented", "faint_grassy", "sour_rotten"],
    tap_sound: Literal["hollow", "solid"],
    thorn_feel: Literal["springy", "rigid"],
) -> dict[str, Any]:
    """Scores the ripeness clues that only a human buyer can smell, hear, and feel.

    Args:
        aroma: What the buyer smells at the seam of the husk.
        tap_sound: What the buyer hears when tapping the husk.
        thorn_feel: How two thorns feel when the buyer presses them together.
    """
    score = AROMA_POINTS[aroma] + TAP_POINTS[tap_sound] + THORN_POINTS[thorn_feel]
    if aroma == "sour_rotten":
        verdict = "SPOILED"
    elif score >= 7:
        verdict = "RIPE"
    elif score >= 4:
        verdict = "NOT_QUITE_READY"
    else:
        verdict = "UNRIPE"
    return {"status": "OK", "ripeness_score": score, "max_score": 10, "verdict": verdict}

Como essas ferramentas funcionam:

  • O ADK transforma cada função em uma ferramenta que o modelo pode chamar. A docstring se torna a descrição da ferramenta, e a seção Args explica cada parâmetro.
  • As dicas de tipo Literal[...] se tornam opções fixas no esquema da ferramenta. Portanto, o Gemini precisa mapear "cheira um pouco a bebida" para exatamente um valor permitido, como boozy_fermented.
  • get_cultivar_profile retorna um status NOT_FOUND explícito com as chaves compatíveis em vez de inventar uma cultivar.

Adicionar a ferramenta de memória de paladar

Crie app/memory_tools.py:

cloudshell edit ~/durian-advisor/app/memory_tools.py

Cole o seguinte código:

"""Tool that remembers each buyer's durian palate across sessions."""

from typing import Any, Literal

from google.adk.tools import ToolContext


def save_palate_preference(
    favorite_flavors: str,
    bitterness_tolerance: Literal["none", "low", "medium", "high"],
    tool_context: ToolContext,
) -> dict[str, Any]:
    """Saves the buyer's durian taste preferences to their long-term profile.

    Args:
        favorite_flavors: Flavors and textures the buyer enjoys, such as
            'sweet, creamy custard'.
        bitterness_tolerance: How much bitterness the buyer enjoys.
    """
    profile = {
        "favorite_flavors": favorite_flavors,
        "bitterness_tolerance": bitterness_tolerance,
    }
    # The "user:" prefix scopes this key to the buyer, so it follows them
    # into every future session of this app.
    tool_context.state["user:palate_profile"] = profile
    return {"status": "SAVED", "palate_profile": profile}

Como funciona a memória do paladar:

  • O ADK transmite tool_context automaticamente e o oculta do modelo, para que o Gemini veja apenas os dois parâmetros de gosto.
  • O prefixo user: define o escopo da chave de estado para o usuário em vez da sessão atual, de modo que o perfil siga o comprador em cada nova conversa.
  • Não é preciso usar uma ferramenta "get" separada. Os agentes leem o perfil diretamente nas instruções com o marcador de posição {user:palate_profile?}. O ? deixa o marcador de posição vazio quando ainda não há um perfil, em vez de gerar um erro.

🔍 Verifique seu trabalho

Avalie um durião que cheira a álcool, faz um som oco quando batido e tem espinhos flexíveis:

cd ~/durian-advisor && uv run python -c "from app.sensory_tools import evaluate_human_sensory_clues as score; print(score('boozy_fermented', 'hollow', 'springy'))"

Você verá uma saída como:

{'status': 'OK', 'ripeness_score': 9, 'max_score': 10, 'verdict': 'RIPE'}

7. Coordenar agentes especializados

Um único agente que lida com regras de visão, pontuação sensorial e correspondência de paladar em um único comando geralmente fica confuso. Em vez disso, você vai atribuir cada tarefa a um especialista focado e deixar que um coordenador combine as respostas:

  • O vision_inspector_agent lê o cultivo e o frescor da foto e retorna um relatório estruturado.
  • sensory_sommelier_agent avalia o que o comprador cheirou, ouviu e sentiu, e verifica se a cultivar agrada ao paladar dele.
  • durian_advisor conversa com o comprador, salva o paladar dele, chama cada especialista e escreve o veredito final.

Criar o inspetor de visão

Crie app/vision_agent.py:

cloudshell edit ~/durian-advisor/app/vision_agent.py

Cole o seguinte código:

"""Vision inspector: reads the cultivar and freshness from a durian photo."""

from google.adk.agents import Agent
from pydantic import BaseModel, Field


class VisionReport(BaseModel):
    cultivar_key: str = Field(
        description="musang_king, black_thorn, red_prawn, xo_d24, or unknown"
    )
    visual_freshness: int = Field(description="1 (stale) to 10 (freshly fallen)")
    evidence: str = Field(description="The visual markers behind your answer")


vision_inspector_agent = Agent(
    name="vision_inspector_agent",
    description="Identifies a durian's cultivar and visual freshness from the buyer's photo or shell description.",
    mode="single_turn",
    # Specialists only see their tool-call input by default. Opt in to the
    # conversation history so this agent can see the uploaded photo.
    include_contents="default",
    # Report back to the coordinator instead of taking over the conversation.
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
    output_schema=VisionReport,
    instruction="""You are a durian vision inspector. Examine the durian photo or shell description in the conversation.
Cultivar markers:
- 5-point star seam at the base: musang_king
- Dark sunken tip at the base: black_thorn
- Oval body with widely spaced, slightly hooked thorns: red_prawn
- Coin-sized brown ring at the base and dense, sharp thorns: xo_d24
Freshness: a plump, moist, greenish stem and closed seams score high. A dry, shriveled stem or a split, moldy husk scores low.
If the markers are unclear, use 'unknown'.""",
)
  • output_schema=VisionReport faz com que o especialista retorne dados estruturados que o coordenador pode usar.
  • include_contents="default" permite que este especialista veja a conversa, incluindo a foto enviada. Sem ele, um especialista de turno único só vê a solicitação que o coordenador transmite.
  • disallow_transfer_to_parent e disallow_transfer_to_peers removem a ferramenta transfer_to_agent que o ADK daria a esse subagente. Um especialista que vê toda a conversa pode ficar tentado a devolver o chat ao coordenador em vez de retornar o relatório.

Criar o sommelier sensorial

Crie app/sensory_agent.py:

cloudshell edit ~/durian-advisor/app/sensory_agent.py

Cole o seguinte código:

"""Sensory sommelier: scores the buyer's senses and checks palate fit."""

from google.adk.agents import Agent
from pydantic import BaseModel, Field

from .sensory_tools import evaluate_human_sensory_clues, get_cultivar_profile


class SensoryClues(BaseModel):
    cultivar_key: str = Field(description="Cultivar from the vision inspector")
    aroma: str = Field(description="What the buyer smelled at the seam")
    tap_sound: str = Field(description="What the buyer heard when tapping the husk")
    thorn_feel: str = Field(description="How the thorns felt when pressed together")


sensory_sommelier_agent = Agent(
    name="sensory_sommelier_agent",
    description="Scores the smell, sound, and touch clues the buyer reports, and checks the cultivar against their palate.",
    mode="single_turn",
    # Report back to the coordinator instead of taking over the conversation.
    disallow_transfer_to_parent=True,
    disallow_transfer_to_peers=True,
    input_schema=SensoryClues,
    instruction="""You are a durian sensory sommelier.
Buyer palate profile: {user:palate_profile?}

1. Call evaluate_human_sensory_clues with the buyer's aroma, tap sound, and thorn feel.
2. Call get_cultivar_profile for the cultivar.
3. Compare the cultivar's bitterness with the buyer's bitterness tolerance.
Report the ripeness verdict, the palate fit, and one sentence of advice.""",
    tools=[evaluate_human_sensory_clues, get_cultivar_profile],
)
  • input_schema=SensoryClues define o que o coordenador precisa transmitir: o cultivar e os três relatórios sensoriais do comprador, nas próprias palavras. O especialista mapeia essas palavras para os valores permitidos da ferramenta.
  • O {user:palate_profile?} coloca o paladar salvo do comprador na instrução, para que o especialista possa avaliar a adequação sem precisar consultar a memória.
  • Nenhum especialista define model. Ambos herdam o MODEL do coordenador.
  • Os dois especialistas usam as mesmas duas sinalizações de transferência, então cada um sempre se reporta ao coordenador.

Conectar o coordenador

Abra app/agent.py:

cloudshell edit ~/durian-advisor/app/agent.py

Substitua o conteúdo dele pelo coordenador:

"""Durian advisor: a concierge that coordinates vision and sensory specialists."""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from .memory_tools import save_palate_preference
from .sensory_agent import sensory_sommelier_agent
from .vision_agent import vision_inspector_agent

MODEL = "gemini-3.8-flash"

root_agent = Agent(
    name="durian_advisor",
    model=Gemini(model=MODEL, retry_options=types.HttpRetryOptions(attempts=3)),
    description="Durian concierge that combines what the camera sees with what the buyer senses.",
    instruction="""You are a friendly durian concierge helping a buyer at a fruit stall.
Buyer palate profile: {user:palate_profile?}

1. When the buyer shares taste preferences, call save_palate_preference.
2. When the buyer shows or describes a durian, call vision_inspector_agent.
3. A camera cannot smell, hear, or feel. Unless the buyer already reported the seam aroma, tap sound, and thorn feel, ask them to check. Then call sensory_sommelier_agent.
4. Call one specialist at a time. Finish with ONE verdict covering the cultivar, ripeness, and palate fit. If the durian does not suit their palate, suggest a cultivar that does.""",
    tools=[save_palate_preference],
    sub_agents=[vision_inspector_agent, sensory_sommelier_agent],
)

app = App(root_agent=root_agent, name="app")

Como os dois especialistas usam mode="single_turn", o ADK oferece ao coordenador duas ferramentas extras chamadas vision_inspector_agent e sensory_sommelier_agent. A instrução se refere a eles por esses nomes.

Testar o coordenador no Playground

Inicie o playground novamente:

cd ~/durian-advisor && agents-cli playground

Abra a Visualização da Web na porta 8080 e converse brevemente com o agente.

Ensine seu paladar:

Hi! Please remember my taste: I love sweet, creamy custard durians and I can't stand bitterness.

Abra a guia Estado. Você verá seu perfil salvo, semelhante a:

{
  "user:palate_profile": {
    "favorite_flavors": "sweet, creamy custard",
    "bitterness_tolerance": "none"
  }
}

Mostre um durião (descreva ou anexe uma foto):

The vendor is showing me a round durian with a coin-sized brown ring at the base and dense, sharp thorns. The stem is green and moist. Should I buy it?

O coordenador chama vision_inspector_agent, que identifica um XO D24. Em seguida, ele pede para você cheirar a costura, bater na casca e pressionar dois espinhos juntos.

Relate o que você percebeu:

It smells a bit boozy, the knock sounds hollow, and the thorns spring back when I press them.

Comece do zero: clique em Nova sessão e pergunte:

Which durian should I pick today?

🔍 Verifique seu trabalho

  • Depois que você relata suas sensações, o coordenador chama sensory_sommelier_agent e dá um veredito: o XO D24 está maduro (9 de 10), mas o amargor dele não combina com seu paladar. Por isso, peça um Red Prawn (D175) ou um Black Thorn (D200).
  • Na guia Eventos, é possível ver durian_advisor chamar cada especialista e sensory_sommelier_agent chamar evaluate_human_sensory_clues e get_cultivar_profile.
  • Na nova sessão, o agente já conhece seu paladar e recomenda uma variedade doce e sem amargor, sem perguntar novamente.

Pressione Ctrl + C no terminal para interromper o playground.

8. Implantar com o Antigravity (opcional)

Você criou e testou o agente manualmente. Agora, você vai deixar que a CLI do Antigravity (agy), o agente de programação com IA do Google para o terminal, faça a implantação. As habilidades da Agents CLI ensinam o Antigravity a implantar um agente do ADK corretamente.

Ativar as APIs de implantação

Ative as APIs Cloud Run, Cloud Build e API Artifact Registry, que a Agents CLI usa para criar e hospedar seu agente:

gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com

Você verá uma saída como:

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

Instalar as habilidades da Agents CLI

Instale as sete habilidades da Agents CLI na pasta do projeto, onde o Antigravity as descobre automaticamente:

cd ~/durian-advisor && agents-cli setup --workspace

🔍 Verifique seu trabalho

ls -1 ~/durian-advisor/.agents/skills

Você verá uma saída como:

google-agents-cli-adk-code
google-agents-cli-deploy
google-agents-cli-eval
google-agents-cli-observability
google-agents-cli-publish
google-agents-cli-scaffold
google-agents-cli-workflow

Iniciar a CLI do Antigravity

A CLI do Antigravity está pré-instalada no Cloud Shell. Inicie-o na pasta do projeto:

cd ~/durian-advisor && agy --dangerously-skip-permissions

Na primeira execução, o Antigravity pede que você faça login com sua Conta do Google, escolha um tema de cores, aceite os Termos de Serviço e confie na pasta atual.

Peça para o Antigravity implantar

Cole este comando no Antigravity:

Use the google-agents-cli-deploy skill to deploy this ADK agent to Cloud Run in us-central1 as a private service. Keep GOOGLE_CLOUD_LOCATION=global so Gemini keeps working, save the exact service URL to .env as AGENT_BASE_URL, and smoke-test the deployed agent with agents-cli run.

O Antigravity lê a habilidade e pode executar os testes do projeto primeiro. Em seguida, ele executa agents-cli deploy, que cria o contêiner com o Cloud Build, implanta o serviço durian-advisor e envia uma mensagem de teste para o serviço ativo. A execução completa leva de cinco a oito minutos.

Quando o Antigravity terminar, saia dele pressionando Ctrl + D duas vezes.

🔍 Verifique seu trabalho

Envie uma mensagem para o agente implantado usando o URL que o Antigravity salvou:

cd ~/durian-advisor && source .env && agents-cli run --url "$AGENT_BASE_URL" --mode adk "Which durian suits a beginner?"

Você verá uma saída como:

Querying remote agent: https://durian-advisor-123456789012.us-central1.run.app (mode: adk)
[user]: Which durian suits a beginner?
[durian_advisor]: For beginners, you want a durian that is sweet, creamy, and gentle on the palate, with little to no bitterness...

Agora confirme se o serviço rejeita chamadas sem um token:

curl -s -o /dev/null -w "%{http_code}\n" "$AGENT_BASE_URL"

Você verá uma saída como:

403

9. Criar o chatbot da Web no estilo vibe coding (opcional)

Seu agente está ativo, mas é particular. Agora você vai retomar a conversa com o Antigravity, que já conhece seu agente, as chaves de estado e o URL dele, e pedir para ele criar e implantar um chatbot da Web para compradores de durião.

Retomar o Antigravity

cd ~/durian-advisor && agy --dangerously-skip-permissions

No Antigravity, execute o seguinte comando de barra e selecione sua conversa de implantação na lista:

/resume

Peça ao Antigravity para criar o chatbot

Cole este comando:

Build a mobile-friendly "Durian Sommelier" web chatbot in a new web/ folder that talks to our deployed agent at AGENT_BASE_URL (ADK app name "app").

- Add palate quick-set buttons, a photo upload, and one-tap sensory chips: Smells sweet, Smells boozy, Hollow knock, Solid knock, Thorns spring back, Thorns feel stiff.
- Use a small FastAPI server that proxies chat requests to the agent with a Google ID token, because the agent service is private.
- Show only durian_advisor's replies in the chat, not the specialists' intermediate output.
- Keep a stable user ID per browser and reuse one ADK session, creating a new one if it is missing.

Deploy it to Cloud Run as durian-sommelier-web in us-central1 with public access. Run it as a new service account named durian-sommelier-web that can invoke durian-advisor, and print the URL.

A Antigravity escreve o app, cria a conta de serviço, concede a ela o papel de Invocador do Cloud Run em durian-advisor e implanta o app com o Cloud Build. Ele geralmente testa o endpoint de chat antes de terminar. A execução completa leva cerca de dez minutos. Quando o URL for impresso, saia pressionando Ctrl + D duas vezes.

🔍 Verifique seu trabalho

Abra o URL https://durian-sommelier-web-....run.app que o Antigravity exibiu e:

  1. Toque em um botão de paladar, como o doce e cremoso. O agente confirma que salvou seu paladar.
  2. Faça upload de uma foto de durião ou digite uma breve descrição da casca. O agente identifica o cultivar e pede suas verificações sensoriais.
  3. Toque nos chips sensoriais que correspondem ao seu durião. O agente responde com um veredito que abrange a maturação e o sabor.

10. Limpar

Exclua os recursos criados para que eles parem de gerar cobranças.

Excluir os serviços do Cloud Run

Exclua o chatbot da Web:

gcloud run services delete durian-sommelier-web --region us-central1 --quiet

Exclua o serviço do agente:

gcloud run services delete durian-advisor --region us-central1 --quiet

Excluir a conta de serviço

Exclua a conta de serviço que o chatbot da Web usou:

gcloud iam service-accounts delete "durian-sommelier-web@$(gcloud config get-value project).iam.gserviceaccount.com" --quiet

Excluir as imagens de contêiner

As implantações de origem do Cloud Run enviam a imagem de contêiner de cada serviço para um repositório do Artifact Registry chamado cloud-run-source-deploy, que pode ser compartilhado por outras implantações no seu projeto. Exclua apenas as duas imagens deste codelab e mantenha o repositório.

Exclua a imagem do agente:

gcloud artifacts packages delete durian-advisor --repository cloud-run-source-deploy --location us-central1 --quiet

Exclua a imagem do chatbot da Web:

gcloud artifacts packages delete durian-sommelier-web --repository cloud-run-source-deploy --location us-central1 --quiet

🔍 Verifique seu trabalho

gcloud run services list --region us-central1

Você verá uma saída como:

Listed 0 items.

Excluir os arquivos locais

Remova a pasta do projeto, incluindo as habilidades e o ambiente virtual:

rm -rf ~/durian-advisor

Se quiser, desinstale a Agents CLI:

uv tool uninstall google-agents-cli

Excluir todo o projeto na nuvem do Google (opcional)

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

11. Parabéns

Parabéns! Você criou e testou um sistema multiagente multimodal Sommelier de Durian com o ADK e a Agents CLI. Se você seguiu as etapas opcionais, também implantou o app no Cloud Run com a CLI do Antigravity.

O que você fez até aqui

  • Criou um projeto do ADK com agents-cli create e um agente de visão multimodal com uma única configuração MODEL.
  • Criou ferramentas human-in-the-loop para cheiro, som e toque, além de uma memória de paladar armazenada no estado do ADK com escopo de user:.
  • Dividir o agente em um coordenador durian_advisor e dois especialistas single_turn que ele chama como ferramentas.
  • (Opcional) Usou a CLI do Antigravity com as habilidades da Agents CLI para implantar o agente e um chatbot da Web no Cloud Run

Próximas etapas