Use o HTAP no AlloyDB para potencializar seu sistema de agentes

1. Visão geral

Na Parte 1, transformamos PDFs caóticos e não estruturados em tabelas limpas, inteligentes e estruturadas no BigQuery usando o Knowledge Catalog e o DataScan. Agora temos um data warehouse robusto. Na Parte 2, configuramos o AlloyDB como nossa base transacional e federamos nossas tabelas do BigQuery nele, criando uma camada de dados unificada sem duplicar um único byte.

Hoje, vamos criar o cérebro. Estamos criando um aplicativo multiagente, o "FroyoOS Store Manager", que fica acima dessa camada de dados para responder a perguntas, verificar alérgenos e processar pedidos em tempo real.

O desafio: desacoplar a IA do agente

Ao criar um agente de IA que precisa se comunicar com bancos de dados, o antipadrão mais comum é forçar os dados e a lógica de IA diretamente no aplicativo Python. Isso torna o app frágil, inseguro e incrivelmente difícil de manter à medida que a arquitetura de dados cresce.

Para resolver esse problema, estamos usando o Toolbox do Protocolo de Contexto de Modelo (MCP). O MCP Toolbox atua como nossa camada de abstração de dados unificada. Definimos nossas operações de banco de dados de forma declarativa em um arquivo tools.yaml simples. Implantamos essa caixa de ferramentas como um endpoint seguro e sem servidor no Google Cloud Run. Nosso agente de IA simplesmente se conecta a esse endpoint e diz: "Execute a ferramenta ‘place_order’".

***Importante: se você ainda não fez a Parte 2,este é o momento certo. Temos alguns dados criados nessa parte que são usados neste app.

O poder do HTAP

Antes de começar a criar o agente, vamos falar sobre por que o título deste post chama especificamente o HTAP (processamento transacional/analítico híbrido).

Em uma arquitetura tradicional, se um agente de IA precisasse processar um pedido de usuário em tempo real (uma carga de trabalho transacional OLTP) e comparar milhares de mapeamentos complexos de ingredientes (uma carga de trabalho analítica OLAP), o aplicativo Python teria que conciliar conexões com dois bancos de dados totalmente diferentes. Isso cria latência grave, sobrecarga de segurança e gerenciamento de estado frágil.

Transformamos o AlloyDB em uma potência HTAP federando nativamente nosso data warehouse do BigQuery diretamente no PostgreSQL. Devido a essa arquitetura HTAP, nosso agente de IA hoje só precisa se comunicar com um endpoint de banco de dados. Ele pode inserir transações em tempo real na tabela live_orders e executar verificações analíticas pesadas no conjunto de dados federado do BigQuery froyo_data no mesmo instante, sem duplicar um único byte de dados. Vamos ver como expomos esse mecanismo à nossa IA.

Vamos começar a criar.

O que você vai aprender

• Como configurar o cluster, a instância e a rede do AlloyDB com um clique de botão
• Como configurar a extensão para se preparar para a federação
• Como configurar a federação do BigQuery para o AlloyDB
• Testar

Requisitos

• Um navegador, como o Chrome ou o Firefox.
• Ter um projeto do Google Cloud com o faturamento ativado.
• Conhecimento básico de SQL

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.

Há recursos limitados neste laboratório que podem ser usados mesmo sem uma conta de faturamento. Se você quiser explorar a prática nessa capacidade, terá observações aplicáveis que estão incluídas nos qualificadores "NÃO TEM UMA CONTA DE FATURAMENTO?". Fique atento a elas.

3. Você vai usar o Cloud Shell, um ambiente de linha de comando em execução 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 você já está autenticado e se o projeto está definido como seu ID do projeto usando o seguinte comando:

gcloud auth list

5. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.

gcloud config list project

6. Se você quiser fazer a autenticação

gcloud auth login

7. Se o projeto não estiver definido, use este comando:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>

8. Ative as APIs necessárias: execute este comando para ativar todas as APIs necessárias:

gcloud services enable \
  alloydb.googleapis.com \
  bigquery.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com

Armadilhas e solução de problemas

A síndrome do "projeto fantasma"	Você executou gcloud config set project, mas está olhando para um projeto diferente na interface do console. Verifique o ID do projeto no menu suspenso no canto superior esquerdo.
A barreira de faturamento	Você ativou o projeto, mas esqueceu a conta de faturamento. O AlloyDB é um mecanismo de alto desempenho. Ele não será iniciado se o "tanque de gasolina" (faturamento) estiver vazio.
Atraso na propagação da API	Você clicou em "Ativar APIs", mas a linha de comando ainda diz Service Not Enabled. Aguarde 60 segundos. A nuvem precisa de um momento para ativar os neurônios.
Cotas	Se você estiver usando uma conta de teste nova, poderá atingir uma cota regional para instâncias do AlloyDB. Se us-central1 falhar, tente us-east1.

3. Como preparar os dados

Verifique se os dados estruturados extraídos de PDFs não estruturados estão disponíveis no BigQuery e se a federação do AlloyDB dos dados do BigQuery também está estabelecida e testada. Se você não concluiu essas etapas, este é um bom momento para executar essas etapas simples aqui e aqui para as partes 1 e 2, respectivamente.

Observação:

Se você estiver testando este codelab, não execute a etapa de limpeza da parte 2 (exclusão do cluster e da instância), porque precisamos da orquestração do AlloyDB para o sistema agêntico demonstrado aqui.

Além desses dados que já criamos na parte 2, precisamos criar mais uma tabela na instância do AlloyDB. Acesse o AlloyDB Studio usando o link:

https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio

Mude o nome do cluster no link acima se estiver usando um cluster diferente.

No AlloyDB Studio, em uma nova guia do editor de consultas, execute a seguinte instrução:

CREATE TABLE live_orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100),
    product_id VARCHAR(100),
    quantity INT,
    order_status VARCHAR(50) DEFAULT 'Pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Isso vai criar a tabela live_orders no seu banco de dados.

4. Como definir a abstração (o tools.yaml)

Primeiro, registramos formalmente nossas operações de banco de dados. Criamos um arquivo tools.yaml que define como nosso agente interage com o AlloyDB, que tem dados transacionais e analíticos (dados analíticos da federação do BigQuery).

1. Acesse o terminal do Cloud Shell. Alterne para o modo de edição.
2. Crie uma nova pasta no diretório raiz: "froyo-agent"
3. Dentro da pasta, crie um arquivo tools.yaml e cole o seguinte conteúdo: (substitua pelos seus valores de projeto, cluster, instância e senha)

# tools.yaml
sources:
    alloydb-source:
        kind: "alloydb-postgres"
        project: "*******"
        region: "us-central1"
        cluster: "my-alloydb-cluster"
        instance: "my-primary-inst"
        database: "postgres"
        user: "postgres"
        password: "*******"
        ipType: "private"


tools:
  check_allergens:
    kind: postgres-sql
    source: alloydb-source
    description: Queries the federated BigQuery tables to find allergens for a product.
    statement: |
      SELECT a.allergen_name
      FROM consistsof c
      INNER JOIN product p ON c.product_id = p.product_id
      INNER JOIN ingredient i ON c.ingredient_id = i.ingredient_name
      INNER JOIN containsallergen a ON i.ingredient_id = a.ingredient_id
      WHERE UPPER(p.product_name) LIKE UPPER($1)
    parameters:
      - name: product_name
        type: string
        description: The name of the product to check. (e.g., '%Midnight%')


  place_order:
    kind: postgres-sql
    source: alloydb-source
    description: Inserts a new live transaction into the native AlloyDB orders table.
    statement: |
      INSERT INTO live_orders (customer_name, product_id, quantity)
      VALUES ($1, (SELECT product_id FROM product WHERE product_name ILIKE '%' || $2 || '%' LIMIT 1), $3) RETURNING order_id;
    parameters:
      - name: customer_name
        type: string
        description: The name of the customer placing the order.
      - name: product_name
        type: string
        description: The name of the product being ordered.
      - name: quantity
        type: integer
        description: The quantity of the product being ordered.


toolsets:
  alloydb_tools:
    - check_allergens
    - place_order

Limitamos os recursos do agente a duas ferramentas: verificar alérgenos e fazer pedidos.

5. Como implantar a caixa de ferramentas no Cloud Run

Para disponibilizar isso ao nosso aplicativo, implantamos a caixa de ferramentas com segurança usando a CLI gcloud. Isso cria nosso endpoint da camada de abstração.

4. Alterne para o terminal do Cloud Shell e navegue até o diretório de trabalho executando o comando:

cd froyo-agent

5. Salve o tools.yaml em um secret chamado "tools-froyo":

gcloud secrets create tools-froyo --data-file=tools.yaml

6. Implante o contêiner do MCP Toolbox no Cloud Run

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy toolbox-froyo \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools-froyo:latest" \
    --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network easy-alloydb-vpc \
    --subnet easy-alloydb-subnet \
    --allow-unauthenticated \
    --vpc-egress private-ranges-only

Os valores de "network" e "subnet" precisam ser substituídos se você usou valores diferentes dos que configuramos no codelab da Parte 2.

7. Anote o URL do Cloud Run resultante (por exemplo, https://toolbox-froyo-xxx.run.app).

6. O back-end agêntico (app.py)

Com nosso banco de dados abstraído, o código Python pode se concentrar totalmente na orquestração e no raciocínio.

Estamos usando o Kit de Desenvolvimento de Agente (ADK) com o Flask. O ADK fornece memória de sessão de nível empresarial (InMemorySessionService), o que significa que nosso agente lembra o contexto da conversa. Ele se integra nativamente ao ToolboxSyncClient para extrair nossas ferramentas do Cloud Run.

Confira seu app.py:

https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py

O app simples do Python Flask conecta o agente do ADK às ferramentas que definimos na nossa caixa de ferramentas, que, por sua vez, interage com o AlloyDB (e os dados federados do BigQuery) e responde ao usuário.

NÃO TEM UMA CONTA DE FATURAMENTO?

Se você estiver lendo este codelab de forma prática, mas de alto nível sem uma conta de faturamento, provavelmente não foi possível configurar o job do DataScan ou realizar a inferência do Knowledge Catalog ou a federação do AlloyDB. Ou você perdeu os codelabs 1 e 2. Portanto, aqui estão os dados disponibilizados para que você possa conhecer a arquitetura e o aplicativo:

Etapas para continuar usando os dados com a conta de faturamento:

A.Na pasta raiz do projeto, faça o download destes arquivos do repositório:

1. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.allergen.csv
2. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.consistsof.csv
3. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.containsallergen.csv
4. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.froyo_data_materialized.csv
5. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.ingredient.csv
6. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.product.csv
7. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.suppliedby.csv
8. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.supplier.csv

Esses arquivos precisam estar na mesma pasta do app.py.

B. Crie o arquivo Python chamado app-nobill.py no mesmo caminho

1. Na pasta raiz do projeto, crie um arquivo chamado app-nobill.py e copie o conteúdo de: https://github.com/AbiramiSukumaran/froyo-data/blob/main/app-nobill.py

C. Todos os outros arquivos mencionados no laboratório também precisam estar intactos para esta versão (basta não executar o arquivo app.py)

NÃO TEM UMA CONTA DE FATURAMENTO?

7. A interface e a execução do app

Para oferecer uma experiência adequada aos nossos gerentes de loja, criamos uma interface de usuário elegante e glassmórfica (templates/index.html) com uma barra lateral de catálogo de produtos em tempo real e uma interface de chat interativa.

Você pode encontrar o index.html no arquivo do repositório aqui:

https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html

Antes de executar o aplicativo, verifique se você instalou as dependências criando o arquivo requirements.txt com o seguinte conteúdo:

Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv

e o arquivo .env preenchido:

GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***

No terminal do Cloud Shell, verifique se você está na pasta do projeto e execute os comandos a seguir um por um:

Instale as dependências:

pip install -r requirements.txt

Execução do arquivo Python:

python app.py

NÃO TEM UMA CONTA DE FATURAMENTO?

Nesse caso, em vez de executar o arquivo Python app.py, execute o seguinte:

python app-nobill.py

NÃO TEM UMA CONTA DE FATURAMENTO?

Clique no link que aparece no terminal ou abra http://localhost:8080.

8. O teste final

Vamos clicar em um produto do catálogo para perguntar ao agente:

Does Midnight Swirl have any allergens?

Você vai receber a resposta:

Cenas dos bastidores:

1. O agente do ADK recebe o comando e decide usar a ferramenta check_allergens.
2. Ele chama com segurança o MCP Toolbox no Cloud Run.
3. A caixa de ferramentas executa a consulta no AlloyDB, que é federada instantaneamente ao BigQuery para verificar as relações complexas que criamos na Parte 1.
4. O banco de dados retorna "Soja", que o agente resume na interface.

Em seguida, dizemos:

Order 2 Midnight Swirls for Alice.

O agente transmite a string "Midnight Swirl" para a caixa de ferramentas. O SQL subjacente resolve dinamicamente a string para um ID inteiro via BigQuery, insere o pedido em tempo real no AlloyDB e confirma a transação.

Repositório de código

https://github.com/AbiramiSukumaran/froyo-data

9. Limpar

Depois que este laboratório for concluído, não se esqueça de excluir o cluster e a instância do AlloyDB.

Acesse https://console.cloud.google.com/alloydb/clusters. Selecione o cluster que você quer excluir clicando nas reticências verticais ao lado dele e clique em EXCLUIR.

Isso vai limpar o cluster e as instâncias dele.

10. Parabéns pelo seu agente!

Pense no que acabamos de realizar:

Nosso sistema agêntico bem orquestrado interage apenas com o MCP Toolbox for Databases. Isso, nos bastidores, processa a chamada de ferramenta e os dados para a lógica de IA do nosso aplicativo, mantendo o fluxo simples:

1. Nosso app transacional (em execução no AlloyDB) pode processar sessões de usuários rápidas e simultâneas.
2. Quando ele precisa de dados analíticos pesados ou contexto histórico (como detalhes do fornecedor ou mapeamentos complexos de ingredientes), ele consulta o froyo_dataschema do BigQuery.
3. Zero ETL. Nenhum pipeline de dados quebrando. Nenhum banco de dados dessincronizado. Armazenamos uma vez (no BQ) e computamos onde precisamos.

Agora que nosso agente e a base de dados (analítica e transacional) estão completos, vamos passar para a próxima parte.

A seguir

Nosso agente funciona perfeitamente... no caminho feliz. Na Parte 4, vamos criar um pipeline de avaliação de agente para testar rigorosamente a validade, o fundamento e o desempenho do nosso sistema agêntico. Até lá!