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 disponíveis. Ele também é capaz de tomar decisões autônomas com base na verdade.

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

O Kit de Desenvolvimento de Agente (ADK)

O Kit de Desenvolvimento de Agente (ADK) é um framework flexível e modular para desenvolver e implantar agentes de IA. O ADK permite criar aplicativos sofisticados ao combinar várias instâncias de agentes distintos em um sistema multiagente (MAS, na sigla em inglês).

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

Considerações importantes para um sistema multiagente

Primeiro, é importante ter um entendimento e raciocínio adequados da especialização de cada agente. — "você sabe por que precisa de um subagente específico para algo", resolva isso primeiro.

Segundo, como reunir tudo com um agente raiz para encaminhar e entender cada uma das respostas.

Terceiro, há vários tipos de encaminhamento de agente que podem ser encontrados aqui nesta documentação. Confira qual deles é mais adequado 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 seu sistema multiagente?

O que você vai criar

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

Agente de proposta de reforma
Agente de verificação de conformidade e permissões
Verificação do status do pedido (ferramenta que usa a MCP Toolbox para bancos de dados)

Agente de proposta de reforma, para gerar o documento de proposta de reforma da cozinha.

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

Agente de verificação do 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 essa parte do banco de dados, vamos usar a MCP Toolbox para AlloyDB e implementar a lógica de recuperação de status dos pedidos.

2. MCP

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

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

MCP Toolbox para bancos de dados

A MCP Toolbox para bancos de dados do Google é um servidor MCP de código aberto para bancos de dados. Ele foi projetado com foco na qualidade de produção e no nível empresarial. Ele permite desenvolver ferramentas com mais facilidade, rapidez e segurança, lidando com complexidades como pool 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 seus dados

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

É preciso destacar que isso é anterior ao MCP.

A MCP Toolbox para bancos de dados fica entre o framework de orquestração do seu aplicativo agêntico e o banco de dados, fornecendo um plano de controle usado para modificar, distribuir ou invocar ferramentas. Ele simplifica o gerenciamento das suas ferramentas, oferecendo 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.

Teremos um agente raiz que vai orquestrar 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

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 .

Se você está lendo este artigo e quer receber créditos para começar a usar o Google Cloud e o ADK, use este link para resgatar créditos. Siga as instruções neste link para resgatar. Esse link é válido apenas até o final de maio para resgate.

Clique neste link para ativar o Cloud Shell. É 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.
Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com o ID do seu projeto usando o seguinte comando:

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

Ative as seguintes APIs executando os comandos abaixo:

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

Verifique se você tem o Python 3.9 ou uma versão mais recente.
Consulte a documentação para ver o uso e os comandos gcloud.

4. Configuração do ADK

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

Instale o ADK

pip install google-adk

5. Estrutura do projeto

No terminal do Cloud Shell, execute os comandos a seguir um por um para criar as pastas raiz e de projeto:

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

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

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

6. Código-fonte

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

from . import agent

Acesse agent.py e atualize o arquivo com o seguinte conteúdo do caminho abaixo:

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

Em agent.py, importamos as dependências necessárias, recuperamos os parâmetros de configuração do arquivo .env e definimos o root_agent, que usa uma ferramenta para invocar a ferramenta da caixa de ferramentas.

Acesse requirements.txt e atualize com o conteúdo do seguinte:

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

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 um cluster e uma instância de banco de dados do AlloyDB.

criar um cluster e uma instância

Navegue até a 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.
Selecione CRIAR CLUSTER nessa página:

Você vai ver uma tela como a abaixo. Crie um cluster e uma instância com os seguintes valores. Verifique se os valores correspondem caso você esteja clonando o código do aplicativo do repositório:

ID do cluster: "vector-cluster"
password: "alloydb"
Compatível com o PostgreSQL 16 / recomenda-se usar a versão mais recente
Região: "us-central1"
Rede: "default"

Ao selecionar a rede padrão, uma tela como a abaixo vai aparecer.

Selecione CONFIGURAR CONEXÃO.

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

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

vector-instance. Se não for possível mudar, use o ID da instância em todas as referências futuras.

Para se preparar para configurar a caixa de ferramentas, vamos ativar a conectividade de IP público na nossa instância do AlloyDB para que a nova ferramenta possa acessar o banco de dados.
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 digite ifconfig. No resultado, identifique o endereço 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.
Cole esse IP na caixa de texto "Redes" das redes externas autorizadas na página de edição da instância.

Depois que a rede for configurada, você poderá continuar criando 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. Se tudo der certo, uma tela vai mostrar a 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 criadas ao criar o cluster. Use os seguintes dados para autenticar no PostgreSQL:

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

Depois de se autenticar no AlloyDB Studio, os comandos SQL são inseridos no editor. É possível adicionar várias janelas do Editor usando o sinal de mais à direita da última janela.

Você vai inserir comandos para o 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 a MCP Toolbox for Databases para atuar como o plano de controle de todas as nossas interações com o banco de dados de pedidos no AlloyDB.

8. Configuração da MCP Toolbox para bancos de dados

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, oferecendo 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.

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

Acesse o terminal do Cloud Shell e verifique se o projeto está selecionado e aparece no prompt do terminal. Execute o comando abaixo no terminal do Cloud Shell para acessar o diretório do projeto:

cd adk-renovation-agent

Execute o comando abaixo para fazer o download e instalar a caixa de ferramentas 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

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 "status do pedido" quando o nome do material corresponde ao texto de pesquisa do usuário.

Vamos entender o arquivo tools.yaml

As origens representam as diferentes fontes 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 MCP Toolbox 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 na Web na nuvem, poderá ver o servidor da caixa de ferramentas em execução com sua nova ferramenta chamada "get-order-data".

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 Agente (ADK) na próxima seção, que vai usar essas ferramentas.

Vamos implantar nossa caixa de ferramentas 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 também. As instruções para hospedar isso no Cloud Run estão aqui. Vamos analisar as etapas principais agora.

Inicie um novo terminal do Cloud Shell ou use um terminal 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.
Defina a variável PROJECT_ID para apontar para o ID do projeto do Google Cloud.

export PROJECT_ID="<<YOUR_GOOGLE_CLOUD_PROJECT_ID>>"

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

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.

gcloud iam service-accounts create toolbox-identity

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

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

A última etapa do comando de implantação familiar no 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 vai iniciar o processo de implantação do Toolbox Server 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 [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 com agente.

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

Já criamos a origem para nosso aplicativo de agente. Vamos atualizar isso para incluir uma nova ferramenta da MCP Toolbox for Databases que acabamos de implantar no Cloud Run.

Observe seu arquivo requirements.txt com a origem do repositório:

Estamos incluindo a dependência da MCP Toolbox para bancos de dados em requirements.txt

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

Observe 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 agente de entender as solicitações do usuário e gerar respostas é alimentada por um modelo de linguagem grande (LLM). Seu agente precisa fazer chamadas seguras para esse serviço de LLM externo, o que exige credenciais de autenticação. Sem uma autenticação válida, o serviço de LLM vai negar as solicitações do agente, e ele não vai funcionar.

Receba uma chave de API do Google AI Studio.
Na próxima etapa, em que você configura o arquivo .env, substitua <<your API KEY>> pelo valor real da sua chave de API.

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

Configure 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>>

Substitua os marcadores pelos seus valores.

11. Executar o agente

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

cd renovation-agent

Instale as dependências:

pip install -r requirements.txt

Execute o comando a seguir no terminal do Cloud Shell para executar o agente:

adk run .

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

adk web

Teste com os seguintes comandos:

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:

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.

14. Parabéns

Parabéns! Você criou um aplicativo multiagente usando o ADK e o MCP Toolbox for Databases. Para mais informações, consulte a documentação do produto: Kit de desenvolvimento de agentes e MCP Toolbox para bancos de dados.

Criar um app multiagente com o MCP Toolbox para AlloyDB e ADK Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.