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 autônomo de cadeia de suprimentos usando o novo loop Pensar, agir, observar no Gemini 3 Flash. Ela não apenas olha, ela 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 grava código Python (OpenCV) para contar pixels de forma determinística.
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 agente-para-agente usando um agent_card.json padronizado , permitindo que o agente de visão peça estoque de forma autônoma ao agente fornecedor.

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 ativar a Visão autônoma com gemini-3-flash-preview usando a API Gemini.
• Como implementar a pesquisa vetorial usando o operador <=> (distância de cosseno) no AlloyDB.
• Como fazer a ponte entre o Cloud Shell e o AlloyDB usando o proxy de autenticação.

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: [a ser inserido]

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 seu ID do projeto usando o seguinte comando:

gcloud auth list

Pronto!

Agora você está pronto para a configuração com um clique. A próxima seção vai:

• Abrir o Cloud Shell automaticamente
• Clonar o repositório
• Orientar você em toda a configuração em um tutorial interativo

3. Configuração com um clique no Cloud Shell

Simplificamos a configuração em um tutorial guiado do Cloud Shell. Tudo é automatizado: provisionamento de infraestrutura, configuração do AlloyDB, configuração do proxy de autenticação e seed do banco de dados.

Iniciar o tutorial do Cloud Shell

⚠️ IMPORTANTE - Antes de clicar:ao clicar no botão abaixo, você vai ver uma caixa de diálogo de segurança perguntando "Abrir no Cloud Shell". Isso aparece ANTES da clonagem do repositório.

Você precisa:

1. ✅ Marque a caixa: Confiar no repositório
2. ✅ Clique em Confirmar.

Sem isso, o repositório não será clonado.

Tudo pronto? Clique para abrir o projeto com um tutorial detalhado:

Um clique e pronto

O que acontece em seguida:

1. O Cloud Shell é aberto com o repositório pré-clonado.
2. Um painel de tutorial aparece à direita com instruções detalhadas.
3. Você vai receber orientações sobre:

• Como receber sua chave da API Gemini (nível sem custo financeiro disponível)
• Definir o projeto do GCP no terminal
• Executando a configuração (verifica as APIs, ativa se necessário, provisiona o AlloyDB: ~15 minutos)
• Fazer duas mudanças importantes no código (ativar visão e memória)
• Criar o card do agente (protocolo A2A)
• Como iniciar todos os serviços

O tutorial é interativo: cada etapa é numerada e acompanha seu progresso.

📌 Automatizado:o script de configuração verifica a autenticação, as APIs e a configuração do projeto. Ele avisa se algo precisa de atenção.

💡 É seguro reiniciar:se a configuração travar ou falhar, você poderá executar o comando sh setup.sh novamente com segurança. O script detecta as instâncias do AlloyDB e pula o provisionamento, retomando de onde você parou.

Alternativa: configuração manual

Se você preferir o controle manual:

1. Abra o Cloud Shell e verifique se o projeto está definido.

gcloud config get-value project

2. Se necessário, defina seu projeto

gcloud config set project YOUR_PROJECT_ID

3. Clonar o repositório

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

4. Executar configuração

sh setup.sh

Siga as instruções na tela do script de configuração.

Próximas etapas:o tutorial orienta você nas etapas restantes. Depois de concluir, continue para a Seção 4 para entender o que aconteceu nos bastidores.

4. Nos bastidores: proxy de autenticação e propagação de 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 problema: o AlloyDB fica dentro de uma VPC particular. O Cloud Shell está fora dele. A conexão direta não é possível.

A correção:o proxy de autenticação do AlloyDB cria um túnel seguro e autenticado pelo IAM de 127.0.0.1:5432 no Cloud Shell para sua instância do AlloyDB. Se a instância tiver o IP público ativado, o proxy vai usá-lo. Caso contrário, ele se conectará via IP privado da VPC.

O que o setup.sh fez

1. Detectamos automaticamente sua instância do AlloyDB (cluster, região, projeto)
2. Criado .env com todas as credenciais (GEMINI_API_KEY, DB_PASS, detalhes do AlloyDB)
3. Fazer o download e iniciar o proxy de autenticação (com --public-ip, se aplicável)
4. Incluímos no banco de dados oito peças de inventário de amostra e o índice ScaNN.

Seu arquivo .env está pronto. Todas as execuções futuras carregam as credenciais automaticamente.

Verificar se funcionou

Verifique se você ainda está na raiz do repositório.

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

Verificar se o proxy de autenticação está em execução

ps aux | grep alloydb-auth-proxy

O que foi criado

• Tabela de inventário com oito partes e embeddings de 768 dimensões
• Índice ScaNN (idx_inventory_scann) para pesquisa vetorial rápida

Erros comuns:

• "DB_PASS not set": execute setup.sh novamente para recriar .env.
• "Conexão recusada": o proxy de autenticação pode precisar de mais tempo. Aguarde 30 segundos e tente de novo.
• "Nenhuma instância encontrada": verifique a implantação: gcloud alloydb instances list
• Erro de barramento (o proxy de autenticação é encerrado): corrupção binária. Correção: rm alloydb-auth-proxy && sh setup.sh

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. Vamos começar como um servidor A2A e depois corrigir a consulta de vetor.

The Audit: The Amnesiac

Se você consultar o agente de fornecedor agora (com o SQL de marcador de posição), ele vai retornar a primeira linha encontrada, não a correspondência mais próxima. Não há conceito de similaridade. Ele é um amnésico.

Iniciar o agente de fornecedor

O servidor A2A (main.py) delega para 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)

Embeddings semânticos reais

Durante a configuração, o banco de dados foi preenchido com incorporações semânticas reais geradas pelo modelo text-embedding-005 do SDK da IA generativa do Google. Isso garante uma correspondência de similaridade precisa, e não vetores aleatórios. O processo de inicialização leva cerca de 10 segundos para 13 itens de amostra usando a geração de embeddings paralela para criar vetores significativos de 768 dimensões que capturam o significado semântico de cada parte.

AlloyDB Detour: por que o ScaNN?

Observação: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. Ele compacta os vetores para que o índice se ajuste ao cache L2 da CPU. Isso o torna até 10 vezes mais rápido do que o HNSW padrão.

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

O agente é enviado com uma consulta de marcador de posição. Precisamos ativar a pesquisa vetorial do ScaNN.

Etapa 1: abrir o arquivo de inventário

cd agents/supplier-agent

Etapa 2: encontre o TODO em inventory.py

Procure a função find_supplier() por volta das linhas 47 a 60. Você vai ver:

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

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

Etapa 3: substituir o SQL de marcador de posição pela pesquisa vetorial do ScaNN

Exclua estas duas linhas:

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

E substitua por:

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

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.
• LIMIT 1 retorna apenas a correspondência mais próxima
• 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 inicialização.

Erros comuns:

• "Arquivo ou diretório não encontrado": você não está na raiz do repositório. Execute cd para voltar à página inicial e 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
• Database connection failed: Ensure Auth Proxy is still running
• 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. O servidor A2A (main.py) delega para agent_executor.py, que chama agent.py para análise do Gemini.

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 pensar-agir-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".
3. Remova o 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="LOW" 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="LOW",  # 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="LOW"?

Para essa tarefa específica (contagem de itens por execução de código), "BAIXO" oferece um orçamento de raciocínio suficiente para:

• Planejar a estrutura do script Python
• Decidir qual abordagem de processamento de imagens usar
• Verificar se a contagem corresponde ao número de caixas delimitadoras

Usar "ALTA" adicionaria 2 a 3 vezes mais latência e custo sem melhorar a precisão para tarefas determinísticas. Reserve "ALTA" para raciocínios complexos em várias etapas (por exemplo, "Analise essa interrupção na cadeia de suprimentos e recomende três fornecedores alternativos com justificativa".

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 real de visão 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.
• Porta 8081 em uso:encerre o processo atual: 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 habilidade	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", precisará atualizar o código da Control Tower com o URL e o contrato de API dele. Com o A2A, a Control Tower descobre e entende automaticamente os recursos dele usando 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.

A correção: crie o card do agente

Precisamos definir o que o agente do fornecedor pode fazer.

1. Copie agents/supplier-agent/agent_card_skeleton.json para agents/supplier-agent/agent_card.json.
2. Edite o arquivo para substituir os marcadores de posição:

Antes (esqueleto):

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

Depois (suas edições):

{
  "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?"]
  }]
}

3. Reinicie o agente do fornecedor para que ele carregue o novo 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 de novo

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:

• Proxy de autenticação do AlloyDB (se não estiver em execução)
• 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 entre os modos 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 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 do ScaNN no AlloyDB. Exibições de consultas de pesquisa (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 ID 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 suas funcionalidades 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 proxy de autenticação está em execução:

ps aux | grep alloydb-auth-proxy

Problemas de conexão do AlloyDB:

Se você encontrar a mensagem "Falha na conexão com o servidor em 127.0.0.1, porta 5432":

Se você encontrar a mensagem "Falha na conexão com o servidor em 127.0.0.1, porta 5432":

1. Verifique o proxy de autenticação:ps aux | grep alloydb-auth-proxy
2. Verifique se o IP público está ativado:gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
3. Para desenvolvimento local (não no Cloud Shell):
4. Problema: o Cloud Shell funciona automaticamente, mas as máquinas locais precisam de redes autorizadas
5. Solução: execute setup.sh novamente e escolha a opção 1 (autorizar 0.0.0.0/0) quando solicitado.
6. Observação de segurança: mesmo com 0.0.0.0/0, a conexão exige:
7. Credenciais válidas do GCP (Application Default Credentials)
8. Senha do banco de dados
9. Criptografia mTLS (o proxy de autenticação processa isso)

9. Limpeza

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

# From repo root
sh 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.

10. 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

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 criação 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 determinista	Verificada pela comunidade

Outros recursos

Protocolo Agent2Agent (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 pesquisa do Google
• 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

11. Modo desafio: melhore 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 na 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 capacidade de observação 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 isso 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.

12. 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), que é de nível empresarial e está pronto para conformidade.

Esta é 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)
• Conferir a documentação da API Gemini
• Confira a documentação da IA do AlloyDB
• Conheça a execução de código do Gemini