Esta página foi traduzida pela API Cloud Translation.

Criar um assistente de IA de loja de artigos esportivos com o ADK, o MCP Toolbox e o AlloyDB

1. Introdução

O que você vai criar

Neste codelab, você vai aprender a criar um assistente de IA da loja de artigos esportivos. Esse aplicativo de IA de agente de última geração, desenvolvido com ADK, MCP Toolbox e AlloyDB, vai ajudar os usuários com várias tarefas, incluindo:

Pesquisar produtos usando linguagem natural.
Encontrar lojas próximas para comprar produtos recomendados.
Fazer novos pedidos.
Verificar os status dos pedidos atuais.
Atualizar pedidos com métodos de entrega preferenciais.

O que você vai aprender

Provisionamento e preenchimento de um banco de dados do AlloyDB para PostgreSQL.
Configurar a caixa de ferramentas do MCP para bancos de dados com sua instância do AlloyDB para PostgreSQL.
Como projetar e desenvolver um agente de IA usando o Agent Development Kit (ADK) para ajudar com consultas de lojas de artigos esportivos.
Testar seu agente e a MCP Toolbox for Databases em um ambiente de nuvem.
Aproveitar os recursos avançados de consulta do AlloyDB para respostas de agentes inteligentes.

O que é necessário

Para concluir este codelab, você vai precisar de:

Um navegador da Web Chrome.
Uma conta do Gmail.
um projeto do Google Cloud com faturamento ativado

Este codelab foi projetado para desenvolvedores de todos os níveis, incluindo iniciantes.

2. Antes de começar

Esta seção orienta você na configuração inicial necessária no seu projeto do Google Cloud antes de começar a criar o assistente de IA do agente da loja de esportes.

Criar um projeto

No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .
Clique neste link para ativar o Cloud Shell. Clique no botão correspondente no Cloud Shell para alternar entre o terminal do Cloud Shell (para executar comandos da nuvem) e o editor (para criar projetos).

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

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

gcloud config list project

Defina a variável PROJECT_ID usando o seguinte comando:

export PROJECT_ID=[YOUR_PROJECT_ID]

gcloud config set project $PROJECT_ID

Ative as seguintes APIs executando os comandos abaixo:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com

3. Criar a instância do AlloyDB

Nesta seção, você vai configurar o cluster e a instância do banco de dados do AlloyDB e configurar as permissões e a rede necessárias para seu agente de IA.

Primeiro, execute o comando a seguir no terminal do Cloud Shell para criar o cluster do AlloyDB:

gcloud alloydb clusters create alloydb-cluster \
    --password=alloydb\
    --network=default \
    --region=us-central1 \
    --database-version=POSTGRES_16

O AlloyDB depende da conectividade de IP particular para acesso seguro e de alta performance. É necessário alocar um intervalo de IP particular na VPC para que o Google use na conexão de peering de serviço com a infraestrutura de rede de serviços gerenciada pelo Google. Execute este comando:

gcloud compute addresses create peering-range-for-alloydb \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=16 \
    --description="Automatically allocated IP range for service networking" \
    --network=default

Em seguida, crie a conexão de peering de serviço da VPC. Isso permite que a rede de nuvem privada virtual (VPC) do Google Cloud se comunique de maneira segura e privada com os serviços gerenciados do Google, incluindo o AlloyDB. Execute este comando:

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=peering-range-for-alloydb \
--network=default

Agora, crie a instância principal no cluster do AlloyDB. Esse é o endpoint real do banco de dados a que seus aplicativos vão se conectar. Execute o comando a seguir para criar uma instância do AlloyDB:

gcloud alloydb instances create alloydb-inst \
     --instance-type=PRIMARY \
     --cpu-count=2 \
     --region=us-central1 \
     --cluster=alloydb-cluster \
     --availability-type=ZONAL \
     --ssl-mode=ALLOW_UNENCRYPTED_AND_ENCRYPTED

Observação:a criação da instância pode levar aproximadamente 10 minutos. Aguarde a conclusão dessa operação antes de continuar.

Ativar a integração com a Vertex AI

Para permitir que sua instância do AlloyDB execute consultas de pesquisa vetorial (essenciais para funcionalidades de IA, como a pesquisa semântica) e chame modelos implantados na Vertex AI, conceda permissões da Vertex AI ao agente de serviço do AlloyDB.

Primeiro, recupere o número do seu projeto do Google Cloud, já que ele é necessário para a vinculação do IAM.

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Em seguida, conceda à Vertex AI permissão ao agente de serviço do AlloyDB:

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

Ativar IP público

Para se preparar para as próximas etapas, vamos ativar a conectividade de IP público na nossa instância do AlloyDB.

No console, acesse o campo de pesquisa na parte superior central da tela e digite "alloydb". Em seguida, edite e acesse a seção "Conectividade de IP público". Marque a caixa de seleção "Ativar IP público" e insira o endereço IP da sua máquina do Cloud Shell.

Para conferir o IP da sua máquina do Cloud Shell, acesse o terminal do Cloud Shell e insira o comando "ifconfig | grep -A 1 eth0". No resultado, substitua os dois últimos dígitos por 0,0 com um tamanho de máscara "/16". Por exemplo, "XX.XX.0.0/16", em que XX são números.

Cole esse IP na caixa de texto "Redes" das redes externas autorizadas na página de edição da instância.

Observação:a operação de atualização pode levar até 3 minutos.

4. Carregar o banco de dados

Criar o banco de dados da loja

Agora é hora de criar seu banco de dados e carregar os dados iniciais da loja de artigos esportivos.

Para permitir que o psql se conecte à sua instância particular do AlloyDB no Cloud Shell, use o proxy de autenticação do AlloyDB. Esse utilitário faz um túnel seguro da sua conexão com o banco de dados. Consulte Proxy de autenticação do AlloyDB.

Faça o download do proxy de autenticação do AlloyDB usando o seguinte comando:

wget https://storage.googleapis.com/alloydb-auth-proxy/v1.13.3/alloydb-auth-proxy.linux.amd64 -O alloydb-auth-proxy

Torne-o executável:

chmod +x alloydb-auth-proxy

Execute este comando na primeira janela do terminal do Cloud Shell. O proxy será executado em segundo plano e encaminhará as conexões.

./alloydb-auth-proxy "projects/$PROJECT_ID/locations/us-central1/clusters/alloydb-cluster/instances/alloydb-inst" --public-ip

Importante:deixe essa janela do terminal aberta e executando o proxy. Não feche.

Abra uma nova janela de terminal no Cloud Shell. Para isso, clique no ícone + ao lado da guia "Terminal do Cloud Shell" na parte de cima.

Conecte-se à instância do AlloyDB usando psql:

psql -h 127.0.0.1 -U postgres

Observação:quando solicitado, insira a senha definida para o usuário postgres durante a criação do cluster. Se você estiver seguindo a documentação diretamente, a senha será alloydb.

E crie o banco de dados de armazenamento para nosso aplicativo (execute os comandos um por um):

CREATE DATABASE store;
\c store
exit

Código-fonte

Agora, clone o repositório de código-fonte do codelab. Verifique se você está no diretório inicial ou em um local adequado antes de clonar e execute o seguinte comando:

git clone https://github.com/mtoscano84/sports-agent-adk-mcp-alloydb.git

Preencher o banco de dados

Navegue até a pasta data do projeto clonado para acessar o arquivo de despejo do banco de dados.

cd sports-agent-adk-mcp-alloydb/data

Em seguida, importe o conjunto de dados de amostra para seu banco de dados store usando o arquivo store_backup.sql do repositório.

psql -h 127.0.0.1 -U postgres -d store -f store_backup.sql

Observação:talvez você veja algumas mensagens de AVISO e ERRO durante essa importação, que podem ser ignoradas com segurança neste codelab. Esses erros geralmente estão relacionados a permissões ou objetos que já existem se o despejo contiver o esquema completo. Você vai encontrar alguns AVISOS e ERROS que podem ser ignorados.

5. Configuração do serviço de autorização

Nesta seção, você vai configurar o serviço de autorização para seu aplicativo. Esse serviço é essencial para proteger o acesso e oferecer proteção contra vulnerabilidades de injeção de comando no seu agente de IA.

Primeiro, adicione um usuário de amostra à tabela users no banco de dados store. Esse usuário será usado para autenticação no seu aplicativo.

Acesse o console, navegue até o AlloyDB, selecione a instância principal e depois o AlloyDB Studio:

Quando solicitado, faça login no AlloyDB Studio usando as credenciais criadas ao configurar o cluster:

Nome de usuário: "postgres"
Banco de dados: "store"
Senha: "alloydb"

No editor de SQL, execute uma instrução INSERT para adicionar o usuário ao banco de dados. Mude o nome, o sobrenome e o endereço de e-mail.

Importante:

Mantenha o LOCAL como está no exemplo
Use o mesmo endereço de e-mail que você está usando para se registrar no console do Google Cloud.

INSERT INTO users (user_id, first_name, last_name, Address, city, postal_code, location, email)
VALUES (10,'John', 'Doe', 'Carrer Muntaner 39', 'Barcelona', '08019', '0101000020E61000008AAE0B3F38B144401FBB0B9414780140', 'john.doe@example.com');

Em seguida, configure a tela de permissão OAuth do seu projeto. Essa tela é apresentada aos usuários quando o aplicativo solicita acesso à Conta do Google deles e define a marca do aplicativo.

No console, acesse "APIs e serviços", "Consentimento do Google OAuth":

Forneça as seguintes informações para criar a marca do seu aplicativo:

Nome do app: "IA do agente de compras de esportes"
E-mail de suporte ao usuário: "YOUR_EMAIL"
Público-alvo: "Externo"
Informações de contato: "YOUR_EMAIL"

Agora, você vai criar o ID do cliente OAuth que seu aplicativo de front-end vai usar para validar a identidade do usuário com o Google.

Primeiro, verifique se você tem o número do projeto do Google Cloud. Isso é necessário para configurar os URIs de redirecionamento corretamente. Execute o comando a seguir em um terminal do Cloud Shell:

Caso a variável PROJECT_ID não esteja definida nesta janela do terminal do Cloud Shell, execute:

export PROJECT_ID=[YOUR_PROJECT_ID]

Em seguida, receba o PROJECT_NUMBER usando o seguinte comando:

gcloud projects describe $PROJECT_ID --format="value(projectNumber)"

Em seguida, acesse "APIs e serviços" -> "Credenciais" -> "Criar credenciais" -> "ID do cliente OAuth".

Use as informações a seguir para criar a credencial:

Tipo de aplicativo: "Aplicativo da Web"
Nome: "Sports Shopping Agent AI App"

Origens JavaScript autorizadas:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

URIs de redirecionamento autorizados:

URL1: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Observação:o URL https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app é o URL de implantação esperado para seu aplicativo de front-end, que será configurado mais tarde neste codelab. Substitua [YOUR_PROJECT_NUMBER] pelo número real que você copiou.

Importante:depois da criação, um pop-up vai mostrar seu ID do cliente OAuth e, às vezes, uma chave secreta do cliente. Armazene o ID do cliente OAuth em um lugar seguro, porque ele será necessário em uma etapa posterior ao configurar o front-end.

6. Configuração do MCP ToolBox for Databases

A caixa de ferramentas fica entre o framework de orquestração do aplicativo e o banco de dados, fornecendo um plano de controle usado para modificar, distribuir ou invocar ferramentas. Ele simplifica o gerenciamento das suas ferramentas ao fornecer um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem precisar reimplantar o aplicativo.

Como um dos bancos de dados compatíveis com o MCP Toolbox for Databases é o AlloyDB, e já provisionamos isso na seção anterior, vamos configurar a caixa de ferramentas.

Primeiro, configure o servidor da caixa de ferramentas do MCP localmente no ambiente do Cloud Shell para verificar a funcionalidade.

No terminal do Cloud Shell, navegue até a pasta toolbox localizada no repositório do projeto clonado:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Execute os comandos a seguir para fazer o download do binário da caixa de ferramentas e conceder permissões de execução:

# see releases page for other versions
export VERSION=0.7.0

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox

chmod +x toolbox

Observação:a versão 0.7.0 é especificada aqui. Em ambientes de produção, sempre verifique e use a versão estável mais recente na página de versões da caixa de ferramentas.

Acesse o editor do Cloud Shell. Para isso, clique no ícone do editor no terminal.

No mesmo diretório sports-agent-adk-mcp-alloydb/src/toolbox, você vai encontrar um arquivo chamado tools.yaml. Abra esse arquivo e atualize os marcadores de posição com seu ID do cliente OAuth e ID do projeto do Google Cloud das etapas anteriores.

Vamos entender o tools.yaml

As fontes representam as diferentes origens de dados com que uma ferramenta pode interagir. Uma origem representa uma fonte de dados com que uma ferramenta pode interagir. É possível definir origens como um mapa na seção "sources" do arquivo tools.yaml. Normalmente, uma configuração de origem contém todas as informações necessárias para se conectar e interagir com o banco de dados.

As ferramentas definem as ações que um agente pode realizar, como ler e gravar em uma fonte. Uma ferramenta representa uma ação que o agente pode realizar, como executar uma instrução SQL. É possível definir ferramentas como um mapa na seção "tools" do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para agir.

Para mais detalhes sobre como configurar o arquivo tools.yaml, consulte esta documentação.

Vamos executar o servidor da caixa de ferramentas MCP para bancos de dados

Execute o seguinte comando (na pasta mcp-toolbox) para iniciar o servidor:

./toolbox --tools-file "tools.yaml"

Agora, se você abrir o servidor no modo de visualização da Web na nuvem, poderá ver o servidor da caixa de ferramentas em execução com todas as ferramentas do aplicativo.

Por padrão, o servidor da caixa de ferramentas do MCP é executado na porta 5000. Vamos usar o Cloud Shell para testar isso.

Clique em "Visualização da Web" no Cloud Shell, conforme mostrado abaixo:

Clique em "Mudar porta", defina a porta como 5000, conforme mostrado abaixo, e clique em "Mudar e visualizar".

Isso vai gerar a saída:

O MCP Toolkit for Databases descreve um SDK do Python para você validar e testar as ferramentas, que está documentado aqui. Vamos pular essa parte e passar direto para o Kit de desenvolvimento de agentes (ADK, na sigla em inglês) na próxima seção, que vai usar essas ferramentas.

Vamos implantar nossa caixa de ferramentas no Cloud Run

Para tornar seu servidor da caixa de ferramentas acessível como um endpoint público que pode ser integrado a outros aplicativos e ao seu agente de IA, implante-o no Cloud Run. Confira instruções detalhadas para hospedar a caixa de ferramentas no Cloud Run neste link.

Volte ao terminal do Cloud Shell e navegue até a pasta da caixa de ferramentas:

cd sports-agent-adk-mcp-alloydb/src/toolbox

Verifique se a variável de ambiente PROJECT_ID está definida como o ID do projeto do Google Cloud.

export PROJECT_ID=$PROJECT_ID

Em seguida, verifique se os seguintes serviços do Google Cloud estão ativados no projeto.

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

Vamos criar uma conta de serviço separada que vai atuar como a identidade do serviço da caixa de ferramentas que vamos implantar no Google Cloud Run. Também estamos garantindo que essa conta de serviço tenha os papéis corretos, ou seja, a capacidade de acessar o Secret Manager e se comunicar com o AlloyDB.

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
   --role roles/secretmanager.secretAccessor


gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/alloydb.client'


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member='serviceAccount:toolbox-identity@'$PROJECT_ID'.iam.gserviceaccount.com' \
    --role='roles/serviceusage.serviceUsageConsumer'

Em seguida, faça upload do arquivo tools.yaml como um secret. Como precisamos instalar a caixa de ferramentas no Cloud Run, vamos usar a imagem de contêiner mais recente para a caixa de ferramentas e definir isso na variável IMAGE.

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

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

Por fim, implante o servidor da caixa de ferramentas no Cloud Run usando o seguinte comando. Esse comando vai colocar seu aplicativo em um contêiner, configurar a conta de serviço, injetar o secret e expô-lo publicamente:

gcloud run deploy toolbox \
--image $IMAGE \
--service-account toolbox-identity \
--region us-central1 \
--set-secrets "/app/tools.yaml=tools:latest" \
--args="--tools_file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
--allow-unauthenticated

Isso vai iniciar o processo de implantação do servidor da caixa de ferramentas com nosso tools.yaml configurado no Cloud Run. Se a implantação for bem-sucedida, você vai receber uma mensagem semelhante a esta:

Deploying container to Cloud Run service [toolbox] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [toolbox] revision [toolbox-00002-dn2] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app

Agora você pode acessar o URL do serviço listado acima no navegador. Ela vai mostrar a mensagem "Hello World" que vimos antes. Além disso, você pode acessar o seguinte URL para conferir as ferramentas disponíveis:

https://toolbox-[YOUR_PROJECT_NUMBER].us-central1.run.app/api/toolset

Você também pode acessar o Cloud Run no console do Google Cloud. O serviço da caixa de ferramentas vai aparecer na lista de serviços do Cloud Run.

7. Agente criado com o ADK

Nesta seção, você vai implantar seu agente de IA, criado com o Agent Development Kit (ADK), no Cloud Run.

Primeiro, ative as APIs necessárias no projeto para criar e implantar o agente no Cloud Run e para interagir com o Artifact Registry e o Cloud Storage. Execute o comando a seguir no terminal do Cloud Shell:

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

Em seguida, vamos atribuir as permissões necessárias à conta de serviço padrão do Compute no nosso projeto. Primeiro, execute o comando a seguir no terminal do Cloud Shell para receber o PROJECT_NUMBER:

PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Atribua permissões à conta de serviço padrão do Compute:

# Grant Cloud Run service account access to GCS
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role="roles/artifactregistry.repoAdmin"

# Grant Vertex AI User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"

# Grant Vertex AI Model User role to the service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.modelUser"

Conectar nosso agente a ferramentas

Vamos conectar nosso agente às ferramentas. No contexto do ADK, uma ferramenta representa uma capacidade específica fornecida a um agente de IA, permitindo que ele execute ações e interaja com o mundo além das habilidades básicas de geração de texto e raciocínio.

No nosso caso, vamos equipar nosso agente com as ferramentas que configuramos na MCP Toolbox for Databases.

Usando o editor do Cloud Shell, navegue até sports-agent-adk-mcp-alloydb/src/backend/ e edite o arquivo "finn_agent.py" com o seguinte código. Observe que estamos usando o URL do serviço do Cloud Run do servidor da caixa de ferramentas do MCP implantado na etapa anterior:

Implantar nosso agente no Cloud Run

Por fim, você vai implantar o agente de IA configurado no Cloud Run, tornando-o acessível por um endpoint HTTP.

Primeiro, crie um repositório do Docker no Artifact Registry para armazenar as imagens de contêiner do agente. Execute o comando a seguir no Cloud Shell:

gcloud artifacts repositories create finn-agent-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-agent images"

Em seguida, crie a imagem do Docker para seu agente usando o Cloud Build. Execute este comando no diretório raiz do projeto clonado (sports-agent-adk-mcp-alloydb/):

gcloud builds submit src/backend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent

Agora, implante o serviço do agente. Esse comando vai criar um serviço do Cloud Run, extrair a imagem do Artifact Registry e configurar variáveis de ambiente.

gcloud run deploy finn-agent \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-agent-images/finn-agent \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID --set-env-vars="GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE"

Observação:estamos definindo variáveis de ambiente de forma dinâmica, incluindo GOOGLE_CLOUD_PROJECT (usando a variável de shell $PROJECT_ID).

Você vai receber uma saída semelhante a esta, indicando a implantação bem-sucedida do seu agente:

Deploying container to Cloud Run service [finn-agent] in project [sports-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-agent] revision [finn-agent-00005-476] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-agent-359225437509.us-central1.run.app

Por fim, teste o agente executando este comando curl no terminal do Cloud Shell:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}' \
  https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app/chat

Você vai receber uma saída semelhante a esta:

"Olá! Sou o Finn, seu assistente de compras de esportes com IA. Posso ajudar você a encontrar produtos, equipamentos e acessórios esportivos. Como posso ajudar você hoje?"

Neste ponto, você validou a implantação do AlloyDB, da caixa de ferramentas do MCP e do seu agente criado usando o ADK.

8. Implantar o front-end

Nesta seção, você vai implantar a interface do usuário de conversação para seu assistente de IA no Cloud Run. Esse front-end é criado usando React e JavaScript.

Antes de fazer a implantação, atualize o código-fonte do front-end com os URLs do agente implantado e o ID do cliente OAuth.

Usando o editor do Cloud Shell, navegue até sports-agent-adk-mcp-alloydb/src/frontend/src/pages/ e abra o arquivo Home.jsx. Você precisará atualizar o marcador de posição do URL do serviço do Cloud Run do seu agente. Em seguida, substitua pelo URL do serviço do Cloud Run do agente da etapa anterior (por exemplo, https://finn-agent-[YOUR_PROJECT_NUMBER].us-central1.run.app).

Agora, navegue até sports-agent-adk-mcp-alloydb/src/frontend/src/components/ e abra o arquivo GoogleSignInButton.jsx. Atualize esse arquivo com o ID do cliente OAuth que você recebeu na seção "Configuração do serviço de autorização":

Implantar o front-end no Cloud Run

Agora que o aplicativo de front-end está configurado, você pode implantá-lo no Cloud Run.

Execute o comando a seguir em um terminal do Cloud Shell no diretório raiz (sports-agent-adk-mcp-alloydb/) para criar um repositório do Docker no Artifact Registry para suas imagens de front-end.

gcloud artifacts repositories create finn-frontend-images \
    --repository-format=docker \
    --location=us-central1 \
    --project=$PROJECT_ID \
    --description="Repository for finn-frontend images"

Em seguida, crie a imagem Docker para o aplicativo de front-end usando o Cloud Build. Execute este comando no diretório raiz do seu projeto:

gcloud builds submit src/frontend/ --tag us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend

Por fim, vamos implantar o front-end no Cloud Run usando o seguinte comando:

gcloud run deploy finn-frontend \
    --image us-central1-docker.pkg.dev/$PROJECT_ID/finn-frontend-images/finn-frontend \
    --platform managed \
    --allow-unauthenticated \
    --region us-central1 \
    --project $PROJECT_ID

Você vai receber uma saída semelhante a esta, indicando a implantação bem-sucedida do front-end:

Deploying container to Cloud Run service [finn-frontend] in project [sport-store-agent-ai] region [us-central1]
OK Deploying... Done.
  OK Creating Revision...
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [finn-frontend] revision [finn-frontend-00002-mwc] has been deployed and is serving 100 percent of traffic.
Service URL: https://finn-frontend-535807247199.us-central1.run.app

Abra seu navegador da Web e use o URL do serviço da etapa anterior para abrir o aplicativo recém-implantado, com tecnologia do seu agente de IA.

9. Executar nosso agente

Seu assistente de IA da loja de esportes, Finn, já está totalmente implantado e pronto para ajudar com as compras.

Abra seu navegador da Web e navegue até o URL do serviço do aplicativo de front-end da etapa anterior. O URL segue este formato: https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app

Depois que o front-end for carregado, clique no botão no canto superior direito (geralmente rotulado como "Fazer login" ou um comando semelhante) para autenticar usando suas credenciais do Google. Essa ação vai usar a configuração do OAuth que você definiu antes.

Depois da autenticação, você pode interagir com o Finn. Clique no botão "Comprar agora" para começar sua experiência de compra por conversa.

Use o script a seguir para testar as várias funcionalidades do seu agente de IA. Copie e cole estes comandos na interface de chat um por um:

Olá, Finn!
Estou procurando tênis de corrida para uma ultramaratona de trilha.
Me dê mais detalhes sobre o Ultra Glide
Adicionar Ultra Glide, tamanho 40, cor vermelho/cinza à minha lista de compras
Mostrar minha lista de compras
Encontrar lojas perto de mim
Faça um pedido usando minha lista de compras na loja Sports Diagonal Mar
Conferir o status dos meus pedidos
Liste os métodos de entrega da loja Sports Diagonal Mar
Atualize o método de entrega para Entrega expressa do meu pedido [YOUR_ORDER_NUMBER]
Conferir o status dos meus pedidos
Obrigado, Finn!

Para uma demonstração visual do agente Finn implantado e dos recursos dele, confira o vídeo abaixo:

Demonstração de um assistente de IA de agente esportivo com tecnologia do AlloyDB

10. Resultados

Depois de executar o script anterior, você validou com êxito a integração completa do seu agente do ADK, a conexão dele com o AlloyDB e a utilização da caixa de ferramentas do MCP. Esta seção destaca os principais recursos que você implementou.

Serviço de autorização

A caixa de ferramentas do MCP para bancos de dados oferece a capacidade de federar um serviço de autorização (especificamente, o Login do Google neste codelab) para autenticar usuários no seu aplicativo. Com a caixa de ferramentas do MCP, seu ID do cliente OAuth é usado para validar a identidade do usuário quando uma ferramenta é invocada.

Esse mecanismo de autenticação robusto oferece uma excelente solução para proteger seu aplicativo de agente contra injeção de comandos, um tipo de ataque em que entradas maliciosas tentam burlar ou manipular o comportamento pretendido do agente. Para mais detalhes, consulte o artigo da Wikipédia sobre injeção de comandos (link em inglês).

Nesse aplicativo, essa técnica é usada quando um usuário pede para "verificar o status dos nossos pedidos" ou "mostrar minha lista de compras". O agente foi projetado para mostrar apenas os pedidos que pertencem ao usuário autenticado, evitando o acesso não autorizado às informações do pedido.

Vector Search

Seu aplicativo agêntico usa o AlloyDB para PostgreSQL para oferecer recursos avançados de consulta, principalmente por meio da pesquisa vetorial. O AlloyDB oferece suporte à geração de embeddings on-line diretamente no banco de dados usando funções SQL.

Com esse recurso avançado, o agente pode traduzir a entrada de linguagem natural de um usuário em uma representação numérica de incorporação. Em seguida, ele pode executar uma pesquisa de similaridade no seu catálogo de produtos (ou outros dados relevantes) com base nesses embeddings, permitindo resultados de pesquisa altamente relevantes.

No seu aplicativo, você usa essa técnica quando pergunta ao Finn: "Estou procurando tênis de corrida para uma ultramaratona".

Recursos geoespaciais (PostGIS)

O AlloyDB para PostgreSQL mantém 100% de compatibilidade com os recursos padrão do PostgreSQL. Neste aplicativo, usamos a extensão popular do PostgreSQL PostGIS para fornecer recursos de localização geoespacial ao agente.

Quando você pergunta ao agente: "Encontre lojas perto de mim", ele executa uma ferramenta que usa índices do PostGIS no banco de dados para localizar com eficiência as lojas mais próximas do local especificado ou inferido pelo usuário.

11. (Opcional) Testar a linguagem natural para SQL da AlloyDB AI

Esta seção apresenta um recurso avançado pré-GA do AlloyDB para PostgreSQL: Linguagem natural para SQL. Com esse recurso, é possível gerar consultas SQL diretamente de comandos de linguagem natural, aproveitando o poder da IA no seu banco de dados.

Importante:como esse é um recurso de pré-GA, é necessário se inscrever e ativar o acesso para seu projeto do Google Cloud, cluster do AlloyDB e banco de dados.

Inscreva-se para ter acesso:preencha este formulário para solicitar acesso ao seu projeto.
Documentação:saiba mais sobre como usar a linguagem natural para SQL da IA do AlloyDB na documentação oficial

Depois de se inscrever e confirmar o acesso ao seu projeto, siga estas etapas no AlloyDB Studio.

Faça login no AlloyDB usando as credenciais criadas ao criar o cluster:

Nome de usuário: "postgres"
Banco de dados: "store"
Senha: "alloydb"

1. Crie a extensão alloydb_ai_nl. Essa extensão fornece as funções necessárias para os recursos de linguagem natural da IA do AlloyDB.

CREATE EXTENSION alloydb_ai_nl cascade;

2. Crie uma configuração para seu aplicativo. Uma configuração define o contexto do esquema que o modelo de IA vai usar para entender seu banco de dados.

SELECT
 alloydb_ai_nl.g_create_configuration(
   'finn_app_config'        -- configuration_id
 );

3. Registre o esquema / tabelas com a configuração. Adicione à configuração as tabelas e os esquemas específicos com que o agente do aplicativo vai interagir.

SELECT alloydb_ai_nl.g_manage_configuration(
   operation => 'register_table_view',
   configuration_id_in => 'finn_app_config',
   table_views_in=>'{public.products, public.products_variants, public.orders, public.orders_items, public.users, public.inventory, public.stores}'
);

4. Gere o contexto para o esquema / tabelas. Essa etapa processa as tabelas registradas para gerar o contexto necessário para o modelo de IA. Esse processo pode levar aproximadamente 2 a 3 minutos.

SELECT alloydb_ai_nl.generate_schema_context(
 'finn_app_config',
 TRUE
);

5. Verifique o contexto gerado automaticamente para tabelas e colunas específicas (opcional). Você pode inspecionar o contexto gerado para entender como o modelo de IA interpreta seu esquema.

SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.inventory';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.name';


SELECT object_context
FROM alloydb_ai_nl.generated_schema_context_view
WHERE schema_object = 'public.products.popularity_score';

Você vai encontrar uma ferramenta chamada "check-inventory-by-store-brand-category" em "tools.yaml" do nosso agente. Essa ferramenta usa a linguagem natural do AlloyDB para SQL:

Abra um navegador da Web e use o URL do serviço para abrir o aplicativo: "https://finn-frontend-[YOUR_PROJECT_NUMBER].us-central1.run.app"

Em seguida, use o seguinte script na interface de chat para testar esse novo recurso:

Olá, Finn!
Qual é a quantidade total de produtos da categoria "Corrida" da Salomon em estoque na loja "Sports Diagonal Mar"?

Para conferir a consulta SQL real que a IA do AlloyDB gerou com base na sua entrada em linguagem natural, volte ao AlloyDB Studio e execute a seguinte consulta:

SELECT
   alloydb_ai_nl.get_sql(
       'finn_app_config',
       'What is the total quantity of category Running products of Salomon in stock at the "Sports Diagonal Mar" store?'
   ) ->> 'sql';

Isso vai mostrar a instrução SQL gerada pela AlloyDB AI.

12. Limpeza

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste laboratório, siga estas etapas:

No console do Google Cloud, acesse a página Gerenciar recursos.
Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
Na caixa de diálogo, digite o ID do projeto e clique em "Encerrar" para excluí-lo.

13. Parabéns

Parabéns! Você criou um aplicativo de IA agêntica orientada por dados usando o ADK, o MCP Toolbox for Databases e o AlloyDB para PostgreSQL.

Para mais informações, consulte a documentação do produto: Kit de desenvolvimento de agentes, Caixa de ferramentas do MCP para bancos de dados e AlloyDB para PostgreSQL.