Crie uma cadeia de suprimentos autônoma com o Gemini 3 Flash e a IA do AlloyDB

1. Visão geral

A era dos "chatbots que leem" está chegando ao fim. Estamos entrando na era da visão agêntica.

Neste codelab, vamos implementar a engenharia de IA determinista, uma prática de criação de sistemas de IA que não fazem suposições. Os modelos de IA padrão costumam "alucinar" (chutar) quando são solicitados a contar itens em uma imagem complexa. Em uma cadeia de suprimentos, um palpite é perigoso. Se uma IA adivinhar que você tem 12 itens quando, na verdade, tem 15, isso vai gerar erros caros.

Vamos criar um agente de cadeia de suprimentos autônoma usando o novo loop Pensar, agir, observar no Gemini 3 Flash. Ele não apenas observa, ele investiga.

A arquitetura determinista

Vamos começar com um sistema "cego" e "amnésico". Você vai "despertar" os sentidos dele manualmente, um por um:

1. The Eyes (agente de visão): ativamos o Gemini 3 Flash com a execução de código. Em vez de prever tokens para adivinhar um número, o modelo escreve código Python (OpenCV) para contar pixels de forma determinista.
2. A memória (agente do fornecedor): ativamos a IA do AlloyDB com o ScaNN (vizinhos mais próximos escalonáveis). Isso permite que o agente se lembre do fornecedor exato de uma peça entre milhões de opções em milissegundos.
3. O handshake (protocolo A2A): ativamos a comunicação Agent-to-Agent usando um agent_card.json padronizado , permitindo que o Vision Agent faça pedidos de estoque de forma autônoma do Supplier Agent.

O que você vai criar

• Um agente de visão que realiza "matemática visual" em transmissões de câmera.
• Um agente de fornecedor com tecnologia AlloyDB ScaNN para pesquisa vetorial de alta velocidade.
• Um front-end da Control Tower com atualizações do WebSocket em tempo real para visualizar o loop autônomo.

O que você vai aprender

• Como configurar o AlloyDB com embeddings vetoriais e índices ScaNN.
• Como ativar a Visão com agentes com gemini-3-flash-preview usando a API Gemini.
• Como implementar a pesquisa vetorial usando o operador <=> (distância de cosseno) no AlloyDB.
• Como conectar agentes ao AlloyDB usando o conector Python do AlloyDB.
• Como usar o protocolo A2A para descoberta dinâmica de agentes.

Requisitos

• Use um navegador, como o Chrome ou o Firefox.
• Ter um projeto do Google Cloud com o faturamento ativado.
• Uma chave da API Gemini (nível sem custo financeiro disponível no Google AI Studio) para o agente de visão.

2. Antes de começar

Criar um projeto

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
2. Confira se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Para testar este codelab, use o link de crédito de faturamento de teste do GCP: https://bit.ly/cvs14-ghj

Como resgatar créditos usando este link? Indique.

3. Você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. Clique em "Ativar o Cloud Shell" na parte de cima do console do Google Cloud.

4. Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com o ID do seu projeto usando o seguinte comando:

gcloud auth list

Configurar banco de dados [AlloyDB]

Antes de mais nada, vamos provisionar o banco de dados. Isso leva cerca de 15 minutos, então vamos começar.

1. Clique no botão abaixo para abrir a ferramenta de configuração do AlloyDB no Cloud Shell:

Abrir no Google Cloud Shell

2. Execute a configuração:

Sh run.sh

3. Use a visualização na Web (ícone de olho 👁️ → Visualizar na porta 8080) para abrir a interface de configuração.
4. Insira o ID do projeto, selecione uma região (por exemplo, us-central1) e crie uma senha do banco de dados.

⚠️ SALVE ESSA SENHA. Você vai precisar dela quando o script de configuração pedir.

5. Clique em "Iniciar implantação" e aguarde cerca de 15 minutos para o provisionamento do cluster.

Buscar o código

Enquanto o AlloyDB provisiona (ou depois que isso for feito), abra o repositório do codelab no Cloud Shell:

Abrir no Google Cloud Shell

⚠️ IMPORTANTE: ao clicar no botão, uma caixa de diálogo de segurança vai aparecer. Marque a caixa "Confiar no repositório" e clique em "Confirmar".

Como alternativa, clone manualmente:

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git

cd visual-commerce-gemini-3-alloydb

Definir o projeto

No terminal do Cloud Shell, confirme se o projeto está definido:

gcloud config set project <YOUR_PROJECT_ID>

Ativar o IP público no AlloyDB

Quando o provisionamento do AlloyDB for concluído, ative o IP público para que o conector Python possa se conectar do Cloud Shell:

1. Acesse o console do AlloyDB.
2. Clique no cluster → clique na instância principal
3. Clique em "Edit".
4. Role a tela até "Conectividade de IP público" e marque "Ativar IP público".
5. Clique em "Atualizar instância"

💡 Observação: o conector Python do AlloyDB processa a autenticação e a criptografia. Não é necessário adicionar redes externas autorizadas.

Conceder permissões da Vertex AI

A conta de serviço do AlloyDB precisa de acesso à Vertex AI para gerar incorporações. Execute o comando na mesma janela do Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Executar o script de configuração

Agora execute o script de configuração. Ele vai detectar automaticamente sua instância do AlloyDB:

sh setup.sh

O que o script faz:

• Valida a CLI gcloud, a autenticação, o projeto e o Python 3
• Verifica e ativa as APIs necessárias (AlloyDB, Vertex AI, Compute, Service Networking)
• Solicita sua chave da API Gemini
• Detecta automaticamente sua instância do AlloyDB e extrai a região, o cluster e o nome da instância
• Pede a senha do banco de dados
• Gera o arquivo de configuração .env
• Instala dependências do Python

💡 Dicas para solução de problemas:

• O projeto errado está no console? Verifique o menu suspenso de projetos no canto superior esquerdo do console.
• O AlloyDB não está sendo criado? O faturamento precisa ser ativado primeiro. O AlloyDB é um mecanismo de alto desempenho e não será provisionado sem ele.
• As APIs mostram "Não ativada" depois da ativação? Aguarde 60 segundos. O atraso de propagação é real.
• Problemas com cotas regionais? Se us-central1 falhar, tente us-east1 ou us-west1.

3. Configuração do banco de dados

Observação:se você usou o tutorial completo do Cloud Shell, tudo isso foi automatizado. Esta seção explica o que aconteceu nos bastidores.

O AlloyDB para PostgreSQL é a base do nosso aplicativo. Vamos usar os recursos vetoriais avançados e o índice ScaNN para ativar a pesquisa semântica quase em tempo real, permitindo que nossos agentes encontrem correspondências de inventário em milhares de registros em milissegundos.

Nesta seção, você vai provisionar o esquema, inserir dados e gerar embeddings, tudo no AlloyDB Studio.

Conectar-se ao AlloyDB Studio

1. Acesse sua instância do AlloyDB no console do AlloyDB.
2. Clique em AlloyDB Studio na navegação à esquerda.
3. Autenticar com:
4. Nome de usuário: postgres
5. Banco de dados: postgres
6. Senha: a senha definida durante a criação do cluster

Ativar extensões

O AlloyDB oferece extensões integradas para vetores e IA. Execute o seguinte SQL no AlloyDB Studio:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;

• google_ml_integration: ativa a função ai.embedding() para chamar a Vertex AI diretamente do SQL.
• vector:armazena e consulta embeddings de vetor de 768 dimensões.
• alloydb_scann: ativa o índice ScaNN do Google para pesquisa vetorial ultrarrápida.

Criar a tabela de inventário

DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    part_name TEXT NOT NULL,
    supplier_name TEXT NOT NULL,
    description TEXT,
    stock_level INT DEFAULT 0,
    part_embedding vector(768)
);

A coluna "part_embedding" armazena vetores de 768 dimensões de "text-embedding-005". É isso que alimenta a pesquisa semântica.

Inserir dados de amostra

Inserir 20 itens de inventário do armazém:

INSERT INTO inventory (part_name, supplier_name, description, stock_level) VALUES
('Cardboard Shipping Box Large', 'Packaging Solutions Inc', 'Heavy-duty corrugated cardboard shipping container, 24x18x12 inches', 250),
('Warehouse Storage Container', 'Industrial Supply Co', 'Stackable plastic storage bin with snap-lock lid, blue', 180),
('Product Shipping Boxes', 'Acme Packaging', 'Medium corrugated boxes for warehouse storage, 18x14x10 inches', 320),
('Industrial Widget X-9', 'Acme Corp', 'Heavy-duty industrial coupling for pneumatic systems', 50),
('Precision Bolt M4', 'Global Fasteners Inc', 'Stainless steel M4 allen bolt, 20mm length, grade A2-70', 200),
('Hexagonal Nut M6', 'Metro Supply Co', 'Galvanized steel hex nut M6, DIN 934 standard', 150),
('Phillips Head Screw 3x20', 'Acme Corp', 'Zinc-plated Phillips head wood screw, 3mm x 20mm', 500),
('Wooden Dowel 10mm', 'Craft Materials Ltd', 'Hardwood birch dowel rod, 10mm diameter x 300mm length', 80),
('Rubber Gasket Small', 'SealTech Industries', 'Buna-N rubber gasket, 25mm OD x 15mm ID, oil resistant', 120),
('Spring Tension 5kg', 'Mechanical Parts Co', 'Stainless steel compression spring, 5kg load capacity', 60),
('Bearing 6204', 'Bearings Direct', 'Deep groove ball bearing 6204-2RS, 20x47x14mm sealed', 45),
('Warehouse Shelf Boxes', 'Storage Systems Ltd', 'Standardized warehouse inventory boxes, corrugated, bulk pack', 400),
('Inventory Container Units', 'Supply Chain Pros', 'Modular stackable storage units for warehouse racking', 95),
('Aluminum Extrusion Bar', 'MetalWorks International', 'T-slot aluminum extrusion 20x20mm profile, 1 meter length', 110),
('Cable Tie Pack 200mm', 'ElectroParts Depot', 'Nylon cable ties, 200mm x 4.8mm, UV resistant black, pack of 100', 600),
('Hydraulic Hose 1/2 inch', 'FluidPower Systems', 'High-pressure hydraulic hose, 1/2 inch ID, 3000 PSI rated', 35),
('Safety Goggles Clear', 'WorkSafe Equipment Co', 'ANSI Z87.1 rated clear safety goggles, anti-fog coating', 275),
('Packing Tape Industrial', 'Packaging Solutions Inc', 'Heavy-duty polypropylene packing tape, 48mm x 100m, clear', 450),
('Stainless Steel Sheet 1mm', 'MetalWorks International', '304 stainless steel sheet, 1mm thickness, 300x300mm', 70),
('Silicone Sealant Tube', 'SealTech Industries', 'Industrial-grade RTV silicone sealant, 300ml cartridge, grey', 190);

Conceder permissões de incorporação

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Gerar embeddings de vetor

Isso usa a função ai.embedding() integrada do AlloyDB para chamar o modelo text-embedding-005 da Vertex AI diretamente do SQL. Não é necessário código Python:

UPDATE inventory
SET part_embedding = ai.embedding(
    'text-embedding-005',
    part_name || '. ' || description
)::vector
WHERE part_embedding IS NULL;

Isso gera vetores de 768 dimensões que capturam o significado semântico do nome e da descrição de cada peça. O índice ScaNN vai usar esses dados para uma pesquisa de similaridade extremamente rápida. [Isso leva cerca de 3 a 5 minutos]

Criar o índice ScaNN

SET scann.allow_blocked_operations = true;

CREATE INDEX IF NOT EXISTS idx_inventory_scann
ON inventory USING scann (part_embedding cosine)
WITH (num_leaves=5, quantizer='sq8');

Por que usar o ScaNN? A pesquisa vetorial padrão (HNSW) exige muita memória. À medida que seu inventário cresce para 100 milhões de peças, o índice fica muito grande para a RAM. O ScaNN (vizinhos mais próximos escalonáveis) usa a quantização vetorial para compactar os vetores e o índice caber no cache L2 da CPU. Isso o torna até 10 vezes mais rápido do que o HNSW padrão para consultas filtradas.

Verificar se tudo funcionou

SELECT part_name, supplier_name, stock_level,
       (part_embedding IS NOT NULL) as has_embedding
FROM inventory
ORDER BY id;

Você vai ver 20 linhas, todas com has_embedding = true.

💡 Dicas para solução de problemas:

• "Extensão não encontrada"? A instância ainda pode estar sendo atualizada. Aguarde alguns segundos e tente de novo.
• "Permissão negada" na incorporação? A propagação do IAM leva até 60 segundos. Execute as instruções GRANT e UPDATE novamente.
• Divergência de dimensão do vetor? A tabela usa vector(768). Mantenha o text-embedding-005. Outros modelos têm dimensões diferentes.
• O embedding retorna NULL? Verifique se o papel do IAM de usuário da Vertex AI foi concedido à conta de serviço do AlloyDB (consulte a seção anterior).

4. Noções básicas sobre a arquitetura

Antes de fazer mudanças no código, vamos entender como o sistema é criado. A arquitetura segue um padrão progressivo de "despertar":

A pilha do agente

Agente de visão (agents/vision-agent/)

• agent.py: lógica principal do Gemini 3 Flash. Envia imagens ao modelo com a execução de código ativada para que ele escreva Python (OpenCV) e conte os itens de forma determinística.
• agent_executor.py: faz a ponte entre as solicitações de protocolo A2A e a lógica do agente.
• main.py: servidor A2A do Uvicorn que atende /.well-known/agent-card.json e processa solicitações.

Agente de fornecedor (agents/supplier-agent/)

• inventory.py: se conecta ao AlloyDB usando o conector Python do AlloyDB (não é necessário proxy de autenticação). Contém a função find_supplier(), que realiza a pesquisa vetorial do ScaNN.
• agent_executor.py: faz a ponte entre o protocolo A2A e a lógica de pesquisa de inventário.
• main.py: servidor A2A do Uvicorn com card do agente e endpoint de integridade.

Control Tower (frontend/)

• app.py: servidor FastAPI + WebSocket que descobre agentes via A2A, organiza o pipeline de visão → pesquisa → pedido e transmite atualizações em tempo real para o navegador.

O fluxo A2A

• A Control Tower lê /.well-known/agent-card.json de cada agente
• Descobre recursos (habilidades, endpoints) sem URLs codificados
• Envia imagem para o agente do Vision → recebe contagem de itens + descrição
• Envia a descrição como uma consulta de incorporação para o agente do fornecedor → recebe uma correspondência parcial
• Faz pedidos de forma autônoma

A conexão do AlloyDB

O agente do fornecedor usa o conector Python do AlloyDB em vez do proxy de autenticação tradicional:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

Isso processa automaticamente a autenticação do IAM, o SSL/TLS e o roteamento de conexão. Ao fazer a implantação no Cloud Run mais tarde, basta mudar ip_type para "PRIVATE" para acesso à VPC.

5. Etapa 1: a memória (agente do fornecedor)

Observação: se você usou o tutorial do Cloud Shell, já fez essa mudança no código. Esta seção explica por que isso é importante e como funciona.

O agente do fornecedor lembra milhões de peças usando o ScaNN do AlloyDB. No momento, ele vem com uma consulta de marcador de posição, um amnésico que retorna a primeira linha encontrada, independente do que você pesquisar.

The Audit: The Amnesiac

Se você consultar o agente de fornecedores agora, ele vai retornar um resultado aleatório. Não há conceito de similaridade. Vamos corrigir isso.

Iniciar o agente de fornecedores

O servidor A2A (main.py) delega a agent_executor.py, que faz a ponte entre o protocolo e a lógica de negócios em inventory.py.

💡 Dica de solução de problemas:se você receber erros de "endereço já em uso", encerre os processos atuais e tente de novo:

pkill -f uvicorn #Kill all uvicorn processes

Etapa 1: navegar até o diretório do agente

cd agents/supplier-agent

Etapa 2: instalar dependências

pip install -r requirements.txt

Etapa 3: iniciar o servidor do agente

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

O comando > /dev/null 2>&1 & executa o servidor em segundo plano e suprime a saída para não interromper o terminal.

Etapa 4: verificar se o agente está em execução (aguarde de 2 a 3 segundos após o início)

curl http://localhost:8082/.well-known/agent-card.json

Saída esperada:JSON com configuração do agente (deve retornar sem erros)

A correção: implementar o operador <=>

Abra agents/supplier-agent/inventory.py e encontre a função find_supplier() nas linhas 60 a 70. O marcador de posição vai aparecer:

# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

Substitua essas duas linhas por:

sql = """
SELECT part_name, supplier_name,
       part_embedding <=> %s::vector as distance
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_str, embedding_str))

O que isso faz:

• <=> é o operador de distância de cosseno no PostgreSQL.
• ORDER BY part_embedding <=> %s::vector encontra a correspondência mais próxima (menor distância = significado semântico mais próximo)
• %s::vector converte sua matriz de embedding no tipo de vetor do PostgreSQL.
• O índice ScaNN acelera automaticamente essa consulta.

Etapa 4: salve o arquivo (Ctrl+S ou Cmd+S)

O agente agora vai usar a pesquisa semântica em vez de retornar resultados aleatórios.

Verificação

Teste a descoberta de A2A e o inventário:

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

Esperado:agent-card.json retorna o card do agente. O snippet do Python retorna uma peça e um fornecedor dos dados de seed.

Erros comuns:

• "Arquivo ou diretório não encontrado": você não está na raiz do repositório. Execute cd para voltar para casa, depois cd visual-commerce-gemini-3-alloydb ou use pwd para saber onde você está.
• Port 8082 in use: Kill existing process: lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError: instale as dependências: pip install -r requirements.txt
• Falha na conexão com o banco de dados:verifique o arquivo .env e preencha ALLOYDB_REGION, ALLOYDB_CLUSTER e ALLOYDB_INSTANCE.
• Conexão recusada:verifique se o IP público está ativado na sua instância do AlloyDB.
• Falha no script de verificação:confira se a propagação foi concluída na etapa 4.

6. Etapa 2: os olhos (agente de visão)

Observação:se você usou o tutorial do Cloud Shell, já ativou a execução de código. Nesta seção, explicamos a arquitetura e por que essa abordagem elimina alucinações.

Enquanto o banco de dados está acessível, vamos despertar os olhos usando o Gemini 3 Flash. O agente de visão realiza "matemática visual" usando a execução de código.

A auditoria: a alucinação

Se você perguntar a um modelo multimodal padrão "Quantas caixas há nesta imagem bagunçada?", ele vai processar a imagem como uma captura estática e fazer uma estimativa.

• O modelo diz: "Vejo cerca de 12 caixas".
• Realidade: há 15 caixas.
• Resultado: falha na cadeia de suprimentos.

A correção: despertar o ciclo de pensar, agir e observar

Ativamos a execução de código e o ThinkingConfig para que o modelo escreva Python (OpenCV) e faça a contagem de forma determinística.

1. Abra agents/vision-agent/agent.py .
2. Encontre a seção "GenerateContentConfig" (por volta das linhas 68 a 78).
3. Remova a marca de comentário do bloco thinking_config=types.ThinkingConfig(...) e de tools=[types.Tool(code_execution=...)].
4. O cliente já está configurado para usar sua GEMINI_API_KEY do ambiente.

Dica:thinking_level="MINIMAL" equilibra velocidade e precisão. Valores válidos: "MINIMAL", "LOW", "MEDIUM", "HIGH". Requer google-genai>=1.56.0.

Observação sobre a arquitetura:o agente de visão usa a API Gemini (chave de API), enquanto o agente de fornecedor usa incorporações da Vertex AI (credenciais do GCP). Essa abordagem híbrida mantém o componente de visão simples e preserva os recursos de banco de dados de nível empresarial.

Arquivo: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="MINIMAL",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

Por que thinking_level="MINIMAL"?

Para esta tarefa (contagem de itens por execução de código), "MINIMAL" fornece raciocínio suficiente para planejar o script e verificar a contagem. Usar "ALTA" adicionaria uma latência de 2 a 3 vezes sem melhorar a precisão para tarefas determinísticas. Otimização de custo-performance: combine a profundidade do raciocínio com a complexidade da tarefa.

A otimização de custo-performance é uma habilidade essencial para a engenharia de IA de produção: combine a profundidade do raciocínio com a complexidade da tarefa.

Iniciar o agente do Vision

🔄 Verificação do caminho: se você ainda estiver em agents/supplier-agent/, primeiro volte à raiz do repositório com cd ../..

Etapa 1: navegar até o diretório do agente de visão

cd agents/vision-agent

Etapa 2: instalar dependências

pip install -r requirements.txt

Etapa 3: iniciar o servidor do agente de visão

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

O comando > /dev/null 2>&1 & executa o servidor em segundo plano e suprime a saída para não interromper o terminal.

Verificação

Teste de descoberta A2A:

curl http://localhost:8081/.well-known/agent-card.json

Esperado:JSON com nome e habilidades do agente. Você vai testar a contagem de visão real com a interface da Torre de controle na etapa 8.

Erros comuns:

• "Arquivo ou diretório não encontrado": você não está na raiz do repositório. Use cd ../.. para voltar à raiz do repositório ou verifique sua localização com pwd.
• Port 8081 in use:Kill existing process: lsof -ti:8081 | xargs kill -9
• GEMINI_API_KEY não definida: verifique se o arquivo .env existe na raiz do repositório com cat .env | grep GEMINI_API_KEY
• Chave de API inválida: verifique se a chave está correta e não expirou.
• google-genai não encontrado:instale as dependências: pip install -r requirements.txt

7. Etapa 3: o handshake (cartão do agente A2A)

Observação:se você usou o tutorial do Cloud Shell, já criou esse card do agente. Esta seção explica o protocolo A2A e por que ele permite a composição de agentes plug-and-play.

Nosso agente vê o problema (Visão) e conhece o fornecedor (Memória). O protocolo A2A permite a descoberta dinâmica: o front-end aprende a se comunicar com cada agente lendo o card dele.

APIs REST tradicionais x A2A

Aspecto	REST tradicional	Protocolo A2A
Descoberta de endpoints	URLs codificados no arquivo de configuração	Dinâmico via /.well-known/agent-card.json
Descrição da capacidade	Documentação da API (para humanos)	Habilidades (legíveis por máquina)
Integração	Código manual por serviço	Correspondência semântica: "Preciso de uma pesquisa de inventário" → descobre a habilidade
Novo agente adicionado	Atualizar todas as configurações dos clientes	Configuração zero: descoberta automática

Benefício no mundo real:em um microsserviço tradicional, se você adicionar um terceiro "Agente de logística", será necessário atualizar o código da Torre de controle com o URL e o contrato de API dele. Com o A2A, a Control Tower descobre e entende automaticamente os recursos do serviço com descrições de habilidades em linguagem natural.

Por isso, a A2A permite a composição de agentes plug-and-play, o padrão arquitetônico para sistemas autônomos.

Criar o card do agente

🔄 Verificação do caminho: se você ainda estiver em agents/vision-agent/, primeiro volte para a raiz do repositório com cd ../..

O card do agente já está incluído em agents/supplier-agent/agent_card.json. Abra e confira:

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

Personalize o nome, a descrição ou os exemplos para corresponder ao seu caso de uso.

Reinicie o agente do fornecedor para carregar o card:

Etapa 1: interromper o agente em execução

pkill -f "uvicorn main:app.*8082"

Etapa 2: navegar até o diretório do agente

cd agents/supplier-agent

Etapa 3: iniciar o agente novamente

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

O comando > /dev/null 2>&1 & executa o servidor em segundo plano e suprime a saída para não interromper o terminal.

Etapa 4: verifique o novo card do agente (aguarde de 2 a 3 segundos após o início)

curl http://localhost:8082/.well-known/agent-card.json

Saída esperada:JSON com seu nome, descrição e habilidades preenchidos.

8. Etapa 4: a Control Tower

Observação:se você usou o tutorial do Cloud Shell, seus serviços já estão em execução. Pule para a seção "Testar o sistema" abaixo para acessar a Control Tower e assistir o fluxo de trabalho autônomo em ação.

Execute o front-end da Control Tower com FastAPI + WebSockets. Ele descobre agentes via A2A e organiza o loop completo com atualizações em tempo real.

Iniciar todos os serviços

A maneira mais fácil de iniciar todos os serviços:

Verificar se você está na raiz do repositório

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Em seguida,

sh run.sh

Este único comando inicia:

• Agente do Vision na porta 8081
• Agente do fornecedor na porta 8082
• Control Tower na porta 8080

Aguarde cerca de 10 segundos para que todos os serviços sejam inicializados.

💡 Dica de solução de problemas: se run.sh falhar com erros de endereço já em uso:

Encerre todos os serviços e tente de novo

pkill -f uvicorn

sh run.sh

Isso acontece se os serviços ainda estiverem em execução de uma tentativa anterior.

Testar o sistema

Acessar a Control Tower:

1. Clique no botão Visualização da Web (ícone de olho 👁️) na barra de ferramentas do Cloud Shell.
2. Selecione Visualizar na porta 8080.
3. O painel da Control Tower será aberto em uma nova guia.

Observação:o front-end usa WebSockets em tempo real para atualizações de agentes ativos. Os cards dos agentes são atualizados conforme eles pensam, analisam e agem, sem precisar atualizar a página.

Executar a demonstração:

1. Canto superior direito:status da conexão (ponto verde "Ao vivo"), alternância do modo DEMO/AUTO e controles de áudio
2. Central: tela principal do fluxo de trabalho com upload de imagens e visualização de análise
3. Painéis laterais (aparecem durante a análise): linha do tempo do fluxo de trabalho (esquerda), acompanhamento do progresso e visualizador de código (direita)

Opção 1: início rápido (recomendado)

1. Na página inicial, você vai encontrar uma seção "Início rápido" com imagens de exemplo.
2. Clique em qualquer imagem de amostra para iniciar a análise automaticamente.
3. Assista o fluxo de trabalho autônomo (~30 a 45 segundos)

Opção 2: fazer upload do seu próprio arquivo

1. Arraste e solte uma imagem de depósito/prateleira (PNG, JPG, até 10 MB) ou clique para procurar
2. Clique em Iniciar fluxo de trabalho autônomo.
3. Observar o pipeline de quatro estágios

O que acontece:

1. Descoberta de agentes:os modais do protocolo A2A mostram cards do agente do Vision e do agente do fornecedor com habilidades e endpoints.
2. Análise de visão:o Gemini 3 Flash gera e executa código Python (OpenCV) para contar itens. A barra de progresso mostra as subetapas. As caixas delimitadoras são sobrepostas aos itens detectados. O selo de resultado mostra "✓ Verificado por código" ou "~ Estimado"
3. Correspondência de fornecedores:animação da pesquisa vetorial ScaNN do AlloyDB. Consultas de pesquisa exibidas (por exemplo, "caixas de metal industriais"). O card de resultados mostra a peça correspondente, o fornecedor e a pontuação de confiança
4. Pedido feito:cartão de recibo com código do pedido, quantidade e detalhes

Dica: mantenha o modo DEMO ativado (canto superior direito) para pausar em cada etapa das apresentações. No modo AUTO, o fluxo de trabalho é executado continuamente.

O que aconteceu

A Control Tower usou o protocolo A2A para descobrir os dois agentes via /.well-known/agent-card.json, orquestrou a análise de visão (Gemini 3 Flash com execução de código), realizou a pesquisa vetorial (AlloyDB ScaNN) e fez um pedido autônomo, tudo com atualizações do WebSocket em tempo real. Cada agente expõe os próprios recursos pelo padrão A2A, permitindo a composição plug-and-play sem SDKs personalizados. Saiba mais: Protocolo A2A

Solução de problemas

Erros relacionados ao caminho:

• "Arquivo ou diretório não encontrado" ao executar comandos: você não está na raiz do repositório.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

Erros de serviço:

• "Endereço já em uso": os processos de execuções anteriores ainda estão ativos.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

• Serviços não iniciados: verifique se as portas estão ocupadas:

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

• "Conexão recusada" ao AlloyDB:verifique se o IP público está ativado na sua instância do AlloyDB.

9. 🎁 Bônus: implantação no Cloud Run

Opcional: tudo funciona localmente. Mas se você quiser compartilhar sua criação com um URL público:

# From repo root
sh deploy/deploy.sh

O que acontece:

1. Lê sua configuração .env
2. Pede seu nome (mostrado no app implantado)
3. Implanta todos os três serviços como um único contêiner do Cloud Run.
4. Concede papéis do IAM para acesso ao AlloyDB.
5. Gera um URL compartilhável

Os visitantes que abrirem seu URL vão ver um pop-up:

🚀 Implantado por Seu nome — Tecnologia Gemini 3 Flash · IA do AlloyDB · Protocolo A2A

Concluído como parte da 14ª temporada do Code Vipassana

[Teste o codelab →]

10. Limpeza

Para evitar cobranças, destrua todos os recursos com o script de limpeza automatizada:

# From repo root
sh deploy/cleanup.sh

Isso remove com segurança:

• Cluster do AlloyDB (o principal fator de custo)
• Serviços do Cloud Run (se implantados)
• Contas de serviço associadas

O script vai pedir confirmação antes de excluir qualquer coisa.

11. Referências e leitura complementar

Todas as declarações técnicas neste codelab são verificadas na documentação oficial do Google Cloud e da IA do Google.

Documentação oficial

Gemini 3 Flash:

• API Code Execution: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
• Guia para desenvolvedores: https://ai.google.dev/gemini-api/docs/gemini-3
• Documentação do modelo: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
• Ficha do modelo: https://deepmind.google/models/gemini/flash/

IA do AlloyDB e ScaNN:

• Benchmarks de desempenho do ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
• Entenda o índice ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
• Análise detalhada da IA do AlloyDB: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
• Práticas recomendadas para ajuste: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
• Documentação do AlloyDB: https://cloud.google.com/alloydb/docs

MCP Toolbox para bancos de dados (abordagem alternativa):

• Caixa de ferramentas do MCP: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

Informações sobre preços:

• Preços da API Gemini: https://ai.google.dev/gemini-api/docs/pricing
• Preços do AlloyDB: https://cloud.google.com/alloydb/pricing
• Preços da Vertex AI: https://cloud.google.com/vertex-ai/pricing

Declarações de performance verificadas

Recurso	Resgatar	Origem
ScaNN x HNSW (filtrado)	10 vezes mais rápido	Blog do Google Cloud (verificado)
ScaNN x HNSW (padrão)	4 vezes mais rápido	Blog do Google Cloud (verificado)
Consumo de memória do ScaNN	3 a 4 vezes menor	Blog do Google Cloud (verificado)
Tempo de build do índice ScaNN	8 vezes mais rápido	Blog do Google Cloud (verificado)
Tempo limite de execução de código	Máximo de 30 segundos	Documentos do Google Cloud (verificados)
E/S de arquivos de execução de código	Sem suporte	Documentos do Google Cloud (verificados)
Comportamento de temperatura=0	Saída determinística	Verificada pela comunidade

Outros recursos

Protocolo Agent-to-Agent (A2A):

• O A2A padroniza a descoberta e a comunicação de agentes
• Cards de agentes veiculados em /.well-known/agent-card.json
• Padrão emergente para colaboração de agentes autônomos

Pesquisa do ScaNN:

• Com base em 12 anos de Google Research
• Aprimora a Pesquisa Google e o YouTube em grande escala
• Disponibilidade geral: outubro de 2024
• Primeiro índice de vetor do PostgreSQL adequado para milhões a bilhões de vetores

12. Modo desafio: aprimore suas habilidades de agente

Você criou uma cadeia de suprimentos autônoma funcional. Tudo pronto para continuar? Esses desafios aplicam os padrões aprendidos a novos problemas.

Desafio 1: pesquisa baseada em imagens (embeddings multimodais)

Fluxo atual:o agente do Vision conta itens → gera uma consulta de texto → o agente do fornecedor incorpora texto → pesquisa no AlloyDB

Desafio:ignore o texto completamente e envie a imagem cortada diretamente para o Agente do Fornecedor.

Dicas:

1. A execução de código do agente do Vision pode cortar itens individuais da imagem da prateleira
2. O modelo multimodalembedding@001 da Vertex AI pode incorporar imagens diretamente
3. Modificar inventory.py para aceitar bytes de imagem em vez de texto
4. Atualize a descrição da habilidade A2A para indicar "Aceita: imagem/jpeg ou texto"

Por que isso é importante:a pesquisa visual é mais precisa para peças com aparências complexas (variações de cor, danos, diferenças de embalagem).

Desafio 2: capacidade de observação: confiança por meio da transparência

Estado atual:o sistema funciona, mas não é possível ver "por dentro"

Desafio:inspecione os registros de consultas do AlloyDB para provar que a pesquisa vetorial está sendo executada.

Etapas:

• Os insights de consultas são ativados por padrão no AlloyDB. Para verificar isso, execute:

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

• Fazer uma pesquisa de fornecedor na interface
• Confira o SQL executado:

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Saída esperada:você vai ver a consulta ORDER BY part_embedding <=> $1::vector LIMIT 1 exata com o tempo de execução.

Por que isso é importante:a observabilidade gera confiança. Quando as partes interessadas perguntam "Como esse agente toma decisões?", você pode mostrar o plano de consulta, não apenas a saída.

Desafio 3: composição multiagente

Desafio:adicione um terceiro agente (agente de logística) que calcula os custos de frete com base na localização do depósito e no peso do item.

Arquitetura:

• Saídas do Vision Agent: contagem de itens
• Saídas do agente do fornecedor: local do fornecedor
• Entradas do agente de logística (NOVO): destino, peso → saídas: custo de frete + ETA

Dica:o protocolo A2A facilita isso. Basta criar um novo card de agente com uma habilidade calculate_shipping. A Control Tower vai descobrir automaticamente.

Padrão que você está aprendendo:este é o núcleo da arquitetura orientada a agentes, sistemas complexos criados com especialistas pequenos e combináveis.

13. Conclusão

Você migrou do IA generativa para a IA agêntica.

O que criamos:

• Visão:substituímos "adivinhar" por Execução de código (Gemini 3 Flash via chave de API).
• Memória:substituímos a "pesquisa lenta" pelo AlloyDB ScaNN (via GCP).
• Ação:substituímos "Integração de API" pelo protocolo A2A.

Benefícios da arquitetura híbrida:

Este codelab demonstrou uma abordagem híbrida:

• Agente de visão:usa a API Gemini (chave de API). É simples, tem um nível sem custo financeiro disponível e não exige faturamento do GCP.
• Agente do fornecedor:usa o GCP (Vertex AI + AlloyDB) de nível empresarial e pronto para conformidade.

Essa é a arquitetura da economia autônoma. O código é seu.

Próximas etapas

• Receba sua chave da API Gemini (nível sem custo financeiro disponível)
• Explorar a documentação da API Gemini
• Confira a documentação da IA do AlloyDB
• Conheça a execução de código do Gemini