Criar um app multiagente com o MCP Toolbox para AlloyDB e ADK

1. Visão geral

Um agente é um programa autônomo que conversa com um modelo de IA para realizar uma operação baseada em metas usando as ferramentas e o contexto que tem e é capaz de tomar decisões autônomas com base na verdade.

Quando o aplicativo tem vários agentes trabalhando juntos de forma autônoma e conjunta, conforme necessário, para atender ao propósito maior, com cada um dos agentes sendo responsável por uma área de foco específica, ele se torna um sistema multiagente.

O Agent Development Kit (ADK)

O Agent Development Kit (ADK) é um framework flexível e modular para desenvolvimento e implantação de agentes de IA. O ADK oferece suporte à criação de aplicativos sofisticados ao compor várias instâncias de agentes distintas em um sistema multiagente (MAS).

No ADK, um sistema multiagente é um aplicativo em que diferentes agentes, geralmente formando uma hierarquia, colaboram ou se coordenam para alcançar uma meta maior. Estruturar seu aplicativo dessa maneira oferece vantagens significativas, incluindo modularidade, especialização, reutilização, capacidade de manutenção e a capacidade de definir fluxos de controle estruturados usando agentes de fluxo de trabalho dedicados.

Considerações importantes para um sistema multiagente

Primeiro, é importante entender e justificar a especialização de cada agente. — "Você sabe por que precisa de um subagente específico para algo?", primeiro descubra isso.

Segundo, como reuni-los com um agente raiz para encaminhar e entender cada uma das respostas.

Terceiro, há vários tipos de roteamento de agentes que você pode encontrar nesta documentação. Confira qual deles se adapta ao fluxo do seu aplicativo. Além disso, quais são os vários contextos e estados necessários para o controle de fluxo do sistema multiagente.

O que você vai criar

Vamos criar um sistema multiagente para lidar com reformas de cozinha usando a MCP Toolbox para AlloyDB e ADK.

1. Agente de proposta de renovação
2. Agente de verificação de compliance e permissões
3. Verificação do status do pedido (ferramenta usando o MCP Toolbox for Databases)

Renovation Proposal Agent, para gerar o documento de proposta de reforma da cozinha.

Agente de permissões e compliance, para cuidar de permissões e tarefas relacionadas ao compliance.

O agente de verificação de status do pedido, para verificar o status do pedido de materiais trabalhando no banco de dados de gerenciamento de pedidos que configuramos no AlloyDB. Mas, para esta parte do banco de dados, vamos usar o MCP Toolbox for AlloyDB para implementar a lógica de recuperação de status para pedidos.

2. MCP

MCP significa "Protocolo de contexto de modelo", um padrão aberto desenvolvido pela Anthropic que oferece uma maneira consistente de agentes de IA se conectarem a ferramentas, serviços e dados externos. Ele funciona essencialmente como um padrão comum para aplicativos de IA, permitindo que eles interajam perfeitamente com diferentes fontes e ferramentas de dados.

1. Ele usa um modelo cliente-servidor, em que os aplicativos de IA (os hosts) executam o cliente do MCP, que se comunica com os servidores do MCP.
2. Quando um agente de IA precisa acessar uma ferramenta ou dados específicos, ele envia uma solicitação estruturada para o cliente do MCP, que a encaminha para o servidor MCP apropriado.
3. Permite que os modelos de IA acessem dados e ferramentas externas sem precisar de código personalizado para cada integração.
4. Simplifica o processo de criação de agentes e fluxos de trabalho complexos em modelos de linguagem grandes (LLMs).

MCP Toolbox for Databases

O MCP Toolbox for Databases do Google é um servidor MCP de código aberto para bancos de dados. Ele foi projetado para atender às necessidades de produção e de nível empresarial. Ele permite que você desenvolva ferramentas de maneira mais fácil, rápida e segura, lidando com complexidades como agrupamento de conexões, autenticação e muito mais.

Permita que seus agentes acessem dados no seu banco de dados. Como?

Desenvolvimento simplificado:integre ferramentas ao seu agente em menos de 10 linhas de código, reutilize ferramentas entre vários agentes ou frameworks e implante novas versões de ferramentas com mais facilidade.

Melhor desempenho:práticas recomendadas, como pooling de conexões, autenticação e muito mais.

Segurança aprimorada:autenticação integrada para acesso mais seguro aos dados

Observabilidade de ponta a ponta:métricas e rastreamento prontos para uso com suporte integrado ao OpenTelemetry.

MCP é anterior a isso!!!

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

Vamos ter um agente raiz que orquestra esses agentes com base no requisito.

Requisitos

• Use um navegador, como o Chrome ou o Firefox.
• Ter um projeto do Google Cloud com o faturamento ativado.

3. 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. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto .

Se você está lendo este artigo e quer receber créditos para começar a usar o Google Cloud e o ADK, acesse este link para resgatar os créditos. Siga estas instruções para resgatar o código. Este link é válido apenas até o fim de maio.

3. Ative o Cloud Shell clicando neste link. É possível alternar entre o terminal do Cloud Shell (para executar comandos da nuvem) e o editor (para criar projetos) clicando no botão correspondente no Cloud Shell.
4. Depois de se conectar ao Cloud Shell, verifique se você já está autenticado e se o projeto está definido como seu ID 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 o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

7. Ative as APIs a seguir executando os seguintes comandos:

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

8. Instale o Python 3.9 ou versão mais recente.
9. Consulte a documentação para ver o uso e os comandos gcloud.

4. Configuração do ADK

1. Criar e ativar o ambiente virtual (recomendado)

No terminal do Cloud Shell, crie um ambiente virtual:

python -m venv .venv

Ative o ambiente virtual:

source .venv/bin/activate

2. Instalar o ADK

pip install google-adk

5. Estrutura do projeto

3. No Cloud Shell Terminal, execute os comandos abaixo um por um para criar as pastas raiz e de projeto:

mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent

4. Acesse o editor do Cloud Shell e crie a estrutura de projeto a seguir criando os arquivos (vazios para começar):

renovation-agent/
        __init__.py
        agent.py
        .env

6. Código-fonte

1. Acesse init.py e atualize com o seguinte conteúdo:

from . import agent

2. Acesse agent.py e atualize o arquivo com o conteúdo a seguir no seguinte caminho:

https://github.com/AbiramiSukumaran/adk-renovation-agent/blob/main/agent.py

Em agent.py, importamos as dependências necessárias, extraímos os parâmetros de configuração do arquivo .env e definimos o root_agent, que orquestra os três subagentes que pretendemos criar neste aplicativo. Há várias ferramentas que ajudam com as funções principais e de suporte desses subagentes.

3. Verifique se você tem o bucket do Cloud Storage

Isso é para armazenar o documento de proposta gerado pelo agente. Crie e forneça acesso para que o sistema multiagente criado com a Vertex AI possa acessá-lo. Confira como fazer isso:

https://cloud.google.com/storage/docs/creating-buckets#console

1. Dê o nome "next-demo-store" ou qualquer outro nome permitido. Anote isso, porque você precisa atualizar o valor de STORAGE_BUCKET no arquivo .env (na etapa de configuração das variáveis de ambiente).
2. Crie no local us-central1
3. Para configurar o acesso ao bucket, acesse o console do Cloud Storage e o bucket do Storage (no nosso caso, o nome do bucket é "next-demo-storage": https://console.cloud.google.com/storage/browser/next-demo-storage).

Navegue até Permissões > Visualizar principais > Permitir acesso. Selecione "Princípios" como "allUsers" e "Papel" como "Usuário de objetos do Storage".

Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.

7. Configuração do banco de dados

Em uma das ferramentas usadas pelo ordering_agent, chamada "check_status", acessamos o banco de dados de pedidos do AlloyDB para conferir o status dos pedidos. Nesta seção, vamos configurar o cluster e a instância do banco de dados AlloyDB.

Criar um cluster e uma instância

1. Navegue pela página do AlloyDB no Console do Cloud. Uma maneira fácil de encontrar a maioria das páginas no console do Cloud é pesquisar usando a barra de pesquisa do console.
2. Selecione CREATE CLUSTER nessa página:

3. Uma tela como esta vai aparecer. Crie um cluster e uma instância com os seguintes valores. Confira se os valores correspondem ao clonar o código do aplicativo do repositório:

• ID do cluster: "vector-cluster"
• senha: "alloydb"
• Compatível com o PostgreSQL 16 / a versão mais recente é recomendada
• Região: "us-central1"
• Redes: "default"

4. Ao selecionar a rede padrão, uma tela como a mostrada abaixo será exibida.

Selecione CONFIGURAR CONEXÃO.

5. Em seguida, selecione Usar um intervalo de IP alocado automaticamente e clique em "Continuar". Depois de analisar as informações, selecione CRIAR CONEXÃO.

6. OBSERVAÇÃO IMPORTANTE: mude o ID da instância (que você encontra no momento da configuração do cluster / instância) para

vector-instance. Se não for possível fazer isso, lembre-se de usar o ID da instância em todas as próximas referências.

7. Para preparar a configuração da Toolbox, vamos ativar o IP público na nossa instância do AlloyDB para que a nova ferramenta possa acessar o banco de dados.
8. 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.
9. Para conferir o IP da sua máquina do Cloud Shell, acesse o terminal do Cloud Shell e digite "ifconfig". No resultado, identifique o endereço de inet eth0 e 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.
10. Cole esse IP na caixa de texto "Redes" das redes externas autorizadas da página de edição da instância.

4. Depois que a rede estiver configurada, você poderá continuar a criar o cluster. Clique em CRIAR CLUSTER para concluir a configuração do cluster, conforme mostrado abaixo:

A criação do cluster leva cerca de 10 minutos. Depois que a criação for concluída, uma tela vai mostrar uma visão geral do cluster que você acabou de criar.

Ingestão de dados

Agora é hora de adicionar uma tabela com os dados da loja. Acesse o AlloyDB, selecione o cluster principal e o AlloyDB Studio:

Talvez seja necessário aguardar a conclusão da criação da instância. Depois disso, faça login no AlloyDB usando as credenciais que você criou ao criar o cluster. Use os seguintes dados para autenticação no PostgreSQL:

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

Depois que você se autenticar no AlloyDB Studio, os comandos SQL serão inseridos no Editor. É possível adicionar várias janelas do Editor usando o sinal de adição à direita da última janela.

Você vai inserir comandos do AlloyDB nas janelas do editor usando as opções Executar, Formatar e Limpar conforme necessário.

Criar uma tabela

É possível criar uma tabela usando a instrução DDL abaixo no AlloyDB Studio:

-- Table DDL for Procurement Material Order Status

CREATE TABLE material_order_status (
    order_id VARCHAR(50) PRIMARY KEY,
    material_name VARCHAR(100) NOT NULL,
    supplier_name VARCHAR(100) NOT NULL,
    order_date DATE NOT NULL,
    estimated_delivery_date DATE,
    actual_delivery_date DATE,
    quantity_ordered INT NOT NULL,
    quantity_received INT,
    unit_price DECIMAL(10, 2) NOT NULL,
    total_amount DECIMAL(12, 2),
    order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
    delivery_address VARCHAR(255),
    contact_person VARCHAR(100),
    contact_phone VARCHAR(20),
    tracking_number VARCHAR(100),
    notes TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    quality_check_passed BOOLEAN,  -- Indicates if the material passed quality control
    quality_check_notes TEXT,        -- Notes from the quality control check
    priority VARCHAR(20),            -- e.g., "High", "Medium", "Low"
    project_id VARCHAR(50),          -- Link to a specific project
    receiver_name VARCHAR(100),        -- Name of the person who received the delivery
    return_reason TEXT,               -- Reason for returning material if applicable
    po_number VARCHAR(50)             -- Purchase order number
);

Inserir registros

Copie a instrução de consulta insert do script database_script.sql mencionado acima para o editor.

Clique em Executar.

Agora que o conjunto de dados está pronto, vamos configurar o MCP Toolbox for Databases para atuar como a camada de controle de todas as interações do banco de dados de pedidos no AlloyDB.

8. 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 ferramentas, fornecendo um local centralizado para armazenar e atualizar ferramentas, permitindo que você compartilhe ferramentas entre agentes e aplicativos e atualize essas ferramentas sem necessariamente implantar novamente o aplicativo.

Você pode ver que um dos bancos de dados compatíveis com a Toolbox para bancos de dados do MCP é o AlloyDB. Como já provisionamos isso na seção anterior, vamos configurar a Toolbox.

1. Acesse o Cloud Shell Terminal e verifique se o projeto está selecionado e mostrado no prompt do terminal. Execute o comando abaixo no terminal do Cloud Shell para navegar até o diretório do projeto:

cd adk-renovation-agent

2. Execute o comando abaixo para fazer o download e instalar a Toolbox na nova pasta:

# 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

3. Acesse o editor do Cloud Shell (para o modo de edição de código) e, na pasta raiz do projeto, adicione um arquivo chamado "tools.yaml".

sources:
    alloydb-orders:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "<<YOUR_ALLOYDB_CLUSTER>>"
        instance: "<<YOUR_ALLOYDB_INSTANCE>>"
        database: "<<YOUR_ALLOYDB_DATABASE>>"
        user: "<<YOUR_ALLOYDB_USER>>"
        password: "<<YOUR_ALLOYDB_PASSWORD>>"

tools:
  get-order-data:
    kind: postgres-sql
    source: alloydb-orders
    description: Get the status of an order based on the material description.
    parameters:
      - name: description
        type: string
        description: A description of the material to search for its order status.
    statement: |
      select order_status from material_order_status where lower(material_name) like lower($1) 
      LIMIT 1;

Na parte da consulta (consulte o parâmetro "statement" acima), estamos apenas recuperando o valor do campo order_status quando o nome do material corresponde ao texto de pesquisa do usuário.

Entenda o tools.yaml

Origens representam as diferentes origens de dados com que uma ferramenta pode interagir. Uma fonte representa uma fonte de dados com que uma ferramenta pode interagir. É possível definir as 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 origem. Uma ferramenta representa uma ação que o agente pode realizar, como executar uma instrução SQL. É possível definir as ferramentas como um mapa na seção "tools" do arquivo tools.yaml. Normalmente, uma ferramenta precisa de uma fonte para funcionar.

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

Vamos executar o MCP Toolbox for Databases Server

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

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

Agora, se você abrir o servidor em um modo de visualização da Web na nuvem, poderá conferir o servidor da Toolbox em funcionamento com a nova ferramenta chamada "get-order-data".

O servidor da MCP Toolbox é executado por padrão 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" e defina a porta como 5000, conforme mostrado abaixo, e clique em "Mudar e visualizar".

Isso vai gerar a saída:

O MCP Toolkit para bancos de dados descreve um SDK do Python para você validar e testar as ferramentas, que está documentado aqui. Vamos pular essa etapa e passar diretamente 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 a Toolbox no Cloud Run

Primeiro, podemos começar com o servidor da MCP Toolbox e hospedá-lo no Cloud Run. Isso nos daria um endpoint público que pode ser integrado a qualquer outro aplicativo e/ou aos aplicativos do agente. As instruções para hospedar isso no Cloud Run estão aqui. Vamos conferir as etapas principais.

1. Inicie um novo terminal do Cloud Shell ou use um terminal do Cloud Shell existente. Acesse a pasta do projeto em que o binário da caixa de ferramentas e o tools.yaml estão presentes, neste caso, adk-renovation-agent.
2. Defina a variável PROJECT_ID para apontar para o ID do seu projeto do Google Cloud.

export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"

3. Ative estes serviços do Google Cloud

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

4. Vamos criar uma conta de serviço separada que vai atuar como a identidade do serviço da Toolbox que será implantado no Google Cloud Run.

gcloud iam service-accounts create toolbox-identity

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

6. Vamos fazer upload do arquivo tools.yaml como um secret:

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

Se você já tiver um secret e quiser atualizar a versão dele, execute o seguinte:

gcloud secrets versions add tools --data-file=tools.yaml

Defina uma variável de ambiente para a imagem do contêiner que você quer usar no Cloud Run:

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

7. A última etapa no comando de implantação conhecido para o Cloud Run:

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 deve iniciar o processo de implantação do servidor da Toolbox com o tools.yaml configurado no Cloud Run. Se a implantação for bem-sucedida, uma mensagem semelhante a esta vai aparecer:

Deploying container to Cloud Run service [toolbox] in project [YOUR_PROJECT_ID] region [us-central1]
OK Deploying new service... Done.                                                                                                                                                                                     
  OK Creating Revision...                                                                                                                                                                                             
  OK Routing traffic...                                                                                                                                                                                               
  OK Setting IAM Policy...                                                                                                                                                                                            
Done.                                                                                                                                                                                                                 
Service [toolbox] revision [toolbox-00001-zsk] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-<SOME_ID>.us-central1.run.app

Você já pode usar a ferramenta recém-implantada no seu aplicativo de agente!

Vamos conectar a ferramenta da caixa de ferramentas ao nosso agente.

Já criamos a fonte do nosso sistema multiagente. Vamos atualizar para incluir uma nova ferramenta do MCP Toolbox for Databases que acabamos de implantar no Cloud Run.

1. Modifique o arquivo requirements.txt com a origem do repositório:

Estamos incluindo a dependência do MCP Toolbox for Databases no requirements.txt

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/requirements.txt

2. Modifique o arquivo agent.py com o código do repositório:

Estamos incluindo a ferramenta que invoca o endpoint da caixa de ferramentas para buscar dados de pedidos de um material específico.

https://github.com/AbiramiSukumaran/renovation-agent-adk-mcp-toolbox/blob/main/agent.py

9. Configuração do modelo

A capacidade do seu agente de entender as solicitações dos usuários e gerar respostas é alimentada por um modelo de linguagem grande (LLM). O agente precisa fazer chamadas seguras para esse serviço externo de LLM, que exige credenciais de autenticação. Sem uma autenticação válida, o serviço LLM negará as solicitações do agente, que não vai funcionar.

1. Receba uma chave de API do Google AI Studio.
2. Na próxima etapa, quando você configurar o arquivo .env, substitua <<your API KEY>> pelo valor real da CHAVE DE API.

10. Configuração de variáveis de ambiente

1. Defina os valores dos parâmetros no arquivo .env do modelo. No meu caso, o .env tem estas variáveis:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION=us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT=<<your project id>>
PROJECT_ID=<<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET=next-demo-store <<or your storage bucket name>>

Substitua os marcadores de posição pelos seus valores.

11. Executar o agente

2. Usando o terminal, navegue até o diretório pai do projeto do agente:

cd renovation-agent

3. Instale as dependências:

pip install -r requirements.txt

4. É possível executar o comando a seguir no terminal do Cloud Shell para executar o agente:

adk run .

5. Execute o seguinte para executar em uma interface da Web provisionada pelo ADK:

adk web

6. Teste com as seguintes solicitações:

user>> 

Hello. Check order status for Cement Bags.

12. Resultado

13. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta postagem, siga estas etapas:

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

14. Parabéns

Parabéns! Você criou um aplicativo multiagente usando o ADK e o MCP Toolbox for Databases. Para mais informações, consulte os documentos do produto: Kit de Desenvolvimento de Agentes e MCP Toolbox for Databases.