Implantar um agente com reconhecimento de governança empresarial com o MCP e o Cloud Run

1. Introdução

Este codelab faz parte de uma série de duas partes que mostra como criar um agente de IA generativa com reconhecimento de governança.

Leia a primeira parte desta série, que aborda como estabelecer a base de dados aplicando aspectos do Dataplex a tabelas do BigQuery e testando as regras localmente pela CLI do Gemini. 👉 Leia a Parte 1)

No entanto, testar em uma CLI local é apenas o começo. Para disponibilizar isso para toda a empresa, você precisa de segurança centralizada, conexões padronizadas de ferramentas de IA e uma estrutura de aplicativos adequada para orquestrar a lógica do agente e fornecer uma interface de chat familiar.

Nesta segunda parte, você vai resolver esses desafios e escalar para a produção. Você vai implantar as regras de governança em um servidor MCP central hospedado no Cloud Run. Em seguida, você vai usar o Kit de Desenvolvimento de Agente (ADK) do Google para criar o aplicativo de agente real e conectá-lo às suas ferramentas do MCP, com uma interface da Web profissional.

be15d5f41f0d716c.png

Pré-requisitos

  • Ter um projeto do Google Cloud com o faturamento ativado.
  • Entendimento básico do Cloud Run, das contas de serviço do IAM e do Python.
  • Os conjuntos de dados do BigQuery e os aspectos do Dataplex criados na Parte 1. Não se preocupe se você os excluiu. Abaixo, fornecemos um script rápido para recriá-los.

O que você vai aprender

  • Como usar o Protocolo de Contexto de Modelo (MCP) para padronizar a interação dos agentes de IA com os dados do Google Cloud.
  • Como implantar um servidor MCP seguro no Cloud Run.
  • Como criar um agente de IA usando o Kit de Desenvolvimento de Agente (ADK) e conectá-lo ao back-end do MCP.
  • Como executar a interface do desenvolvedor integrada do ADK para interagir com seu agente controlado.

O que é necessário

  • Acesso ao Google Cloud Shell

Conceitos principais

  • Protocolo de Contexto de Modelo (MCP): pense no MCP como um "cabo USB-C universal" para agentes de IA. Em vez de escrever um código de integração de API personalizado para cada modelo de IA, o MCP oferece uma maneira padrão para que a IA se conecte com segurança às ferramentas de dados da sua empresa, como Dataplex e BigQuery.
  • Kit de desenvolvimento de agentes (ADK): um framework flexível de código aberto do Google projetado para simplificar o desenvolvimento de ponta a ponta de agentes de IA. Ele aplica princípios de engenharia de software à criação de agentes, permitindo orquestrar ferramentas complexas, gerenciar estados e iniciar facilmente uma interface de desenvolvedor integrada para testes e implantação.

2. Configuração e requisitos

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

Ativar o Cloud Shell

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Captura de tela do terminal do Google Cloud Shell mostrando que o ambiente foi conectado

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

Inicializar o ambiente

Abra o Cloud Shell e defina as variáveis do projeto para garantir que todos os comandos sejam direcionados à infraestrutura correta.

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

Checkpoint: retomar ou reconstruir?

Como esta é a Parte 2, seu agente precisa dos dados governados da Parte 1 para funcionar. Escolha seu caminho:

Caminho A: acabei de concluir a Parte 1 e meus recursos ainda estão em execução.

Ótimo! Navegue até o diretório de trabalho e você estará pronto para continuar.

cd ~/devrel-demos/data-analytics/governance-context

Caminho B: pulei a Parte 1 OU excluí meus recursos (limpeza).

Sem problemas. Fornecemos um bloco de comandos de "Fast-Track" abaixo. Isso vai recriar automaticamente o data lake do BigQuery e aplicar os metadados de governança do Dataplex exatamente como fizemos na Parte 1.

# 1. Clone the repo and navigate to the working directory
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

# 2. Rebuild the messy data lake with Terraform
cd terraform
terraform init
terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

# 3. Generate and apply Dataplex Aspects (Governance rules)
cd ..
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. Escalonamento com o MCP: como criar o plano de controle de dados

Até agora, você testou sua lógica de governança usando a CLI do Gemini. Isso é excelente para prototipagem rápida, mas é executado localmente usando suas credenciais de usuário pessoais.

Em um ambiente empresarial real, você precisa de um plano de controle de dados centralizado. Para isso, vamos usar a Toolbox de IA generativa para bancos de dados, um projeto oficial de código aberto do Google. Essa caixa de ferramentas oferece um servidor MCP pré-criado projetado especificamente para conectar agentes de IA com segurança a bancos de dados e serviços de metadados do Google Cloud, como o Dataplex.

Ao implantar essa caixa de ferramentas como nosso servidor MCP no Cloud Run, conseguimos:

  1. Identidade centralizada:o agente é executado como uma conta de serviço restrita, não como sua conta de usuário pessoal.
  2. Padronização:qualquer cliente (ADK, Gemini, apps personalizados) pode se conectar a esse servidor usando o protocolo padrão do MCP.
  3. Escopo controlado (privilégio mínimo): não damos ao LLM acesso aberto ao BigQuery. Forçamos a navegação primeiro pelo catálogo de metadados do Dataplex.

Configurar a definição da ferramenta (tools.yaml)

A caixa de ferramentas de IA generativa exige um arquivo de configuração declarativo, tools.yaml. Esse arquivo define o sources (onde se conectar) e o tools (o que a IA pode fazer).

  1. Navegue até o diretório do servidor e injete o ID do projeto no arquivo de configuração:
cd ~/devrel-demos/data-analytics/governance-context/mcp_server
envsubst < tools.yaml > tools.tmp && mv tools.tmp tools.yaml
cat tools.yaml

Ele precisa ser idêntico ao snippet a seguir. Verifique se o campo do projeto agora corresponde ao seu ID do projeto do Google Cloud.

sources:
  dataplex:
    kind: dataplex
    project: YOUR-PROJECT-ID

tools:
  search_entries:
    kind: dataplex-search-entries
    source: dataplex
    description: Search for entries in Dataplex Catalog.

  lookup_entry:
    kind: dataplex-lookup-entry
    source: dataplex
    description: Retrieve a specific entry from Dataplex Catalog.

  search_aspect_types:
    kind: dataplex-search-aspect-types
    source: dataplex
    description: Find aspect types relevant to a query.

toolsets:
  dataplex-toolset:
    - search_entries
    - lookup_entry
    - search_aspect_types

Ao definir essas três ferramentas, podemos forçar a IA a ser "somente leitura" e "governança em primeiro lugar".

Proteger a configuração (Secret Manager)

Na arquitetura empresarial, nunca incorpore arquivos de configuração diretamente em imagens de contêiner. Vamos armazenar tools.yaml com segurança no Secret Manager do Google Cloud.

gcloud services enable secretmanager.googleapis.com
gcloud secrets create dataplex-tools-config --data-file=tools.yaml

Implementar o princípio do privilégio mínimo (IAM)

Em seguida, criamos uma conta de serviço dedicada para o servidor MCP da caixa de ferramentas de IA generativa. Essa identidade terá apenas as permissões exatas necessárias para ler o catálogo do Dataplex e acessar os dados do BigQuery.

export MCP_SA=mcp-sa
gcloud iam service-accounts create ${MCP_SA} \
    --display-name="Service Account for Dataplex MCP"
export MCP_SERVICE_ACCOUNT="${MCP_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

# Allow the server to read its own config from Secret Manager
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor"

# Allow the server to read Dataplex Metadata and BigQuery Data
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

Implantar o servidor MCP no Cloud Run

Agora, vamos implantar a caixa de ferramentas de IA generativa. Usamos a imagem de contêiner pré-criada do Google (database-toolbox/toolbox) e montamos nossa configuração do Secret Manager (--set-secrets) durante a execução.

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

gcloud run deploy governance-mcp \
    --image=$IMAGE \
    --service-account $MCP_SERVICE_ACCOUNT \
    --region=$REGION \
    --no-allow-unauthenticated \
    --set-secrets="/app/tools.yaml=dataplex-tools-config:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080"

Você estabeleceu uma API gerenciada. Em vez de dar ao front-end da IA generativa acesso direto ao banco de dados, ele se conectará a esse URL do Cloud Run. O agente só pode ver o que a caixa de ferramentas permite.

4. Criar o back-end do agente com o ADK

Você estabeleceu um plano de controle de dados (MCP) seguro e governado em execução no Cloud Run. Agora, seu agente de IA precisa de uma estrutura para orquestrar a lógica, como processar entradas do usuário, decidir quando chamar o servidor MCP e formatar a saída.

Em vez de escrever todo esse código boilerplate do zero, vamos usar o Kit de Desenvolvimento de Agente (ADK) do Google. O ADK é um framework com foco em código que encapsula automaticamente a lógica do seu agente em um back-end do FastAPI. Além disso, ele vem com uma interface do desenvolvedor integrada, permitindo visualizar instantaneamente o processo de raciocínio e as chamadas de ferramentas do agente sem criar um front-end personalizado primeiro.

Inspecionar a lógica do agente (agent.py)

Antes de configurar a infraestrutura, vamos analisar o núcleo desse aplicativo.

Navegue até o diretório e mostre o conteúdo de agent.py. Esse arquivo é o "cérebro" da sua implantação do ADK.

cd ~/devrel-demos/data-analytics/governance-context/mcp_server
cat agent.py

Analise a estrutura do código. Ele realiza três funções essenciais com um mínimo de código boilerplate:

  1. Integração da MCPToolset:em vez de escrever clientes HTTP personalizados para interagir com as ferramentas do Dataplex, o ADK usa MCPToolset(server_url=mcp_url). Isso busca dinamicamente a definição tools.yaml do servidor MCP implantado e a traduz em chamadas de função nativas para o LLM.
  2. Instruções do sistema:o parâmetro instructions contém as regras de governança estritas (a mesma lógica que usamos na CLI GEMINI.md). Ele ordena explicitamente que o modelo execute o loop de raciocínio da Fase 1 (pesquisa de metadados) para a Fase 2 (consulta de dados).
  3. Orquestração de agentes:a classe Agent(...) vincula o modelo do Gemini, o comando do sistema e as ferramentas do MCP. Quando implantado, o ADK converte automaticamente esse objeto em um endpoint escalonável do FastAPI.

Separação de funções: configurar a identidade do front-end

Para executar esse código com segurança, precisamos informar ao agente onde o servidor MCP está localizado. Vamos construir o URL de forma dinâmica e salvá-lo em um arquivo .env que o ADK vai ler no ambiente de execução.

Também vamos criar uma identidade separada (dataplex-agent-sa) para esse aplicativo voltado ao usuário. Essa separação de funções garante que o agente de front-end tenha permissões diferentes do servidor de governança de back-end.

Execute os comandos a seguir para configurar o ambiente e a identidade:

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export MCP_SERVER_URL=https://governance-mcp-${PROJECT_NUMBER}.${REGION}.run.app/mcp

export AGENT_SA=dataplex-agent-sa
export AGENT_SERVICE_ACCOUNT="${AGENT_SA}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create ${AGENT_SA} \
    --display-name="Service Account for Dataplex Agent "

Configurar variáveis de ambiente de execução

O framework ADK depende de variáveis de ambiente para entender o contexto. Precisamos definir explicitamente o ID do projeto, a região e ativar o uso da Vertex AI. Vamos anexar esses dados ao mesmo arquivo .env.

echo MCP_SERVER_URL=$MCP_SERVER_URL > .env
echo GOOGLE_GENAI_USE_VERTEXAI=1 >> .env
echo GOOGLE_CLOUD_PROJECT=$PROJECT_ID >> .env
echo GOOGLE_CLOUD_LOCATION=$REGION >> .env

Conceder permissões

Mesmo que o agente delegue as verificações de governança ao servidor do MCP, ele ainda precisa de permissões básicas para operar. Concedemos exatamente duas funções:

  1. Usuário da Vertex AI:para invocar o modelo do Gemini e gerar respostas em linguagem natural.
  2. Chamador do Cloud Run:para chamar com segurança a API do servidor MCP. Ele não tem acesso direto ao BigQuery ou ao Dataplex.
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud run services add-iam-policy-binding governance-mcp \
  --region=$REGION \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

Implantar no Cloud Run

Por fim, implante a pilha completa no Cloud Run.

Usamos uvx para executar a ferramenta ADK sem instalar dependências manualmente. O comando abaixo empacota a lógica agent.py, cria uma imagem de contêiner, injeta sua conta de serviço e inicia um servidor FastAPI. Ao adicionar a flag --with_ui, ele também agrupa o ADK Web Playground para depuração.

Esse comando cria e implanta o contêiner. Esse processo pode levar de 1 a 3 minutos.

uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service_name=dataplex-agent \
  --with_ui \
  . \
  -- \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated

Quando o comando for concluído, ele vai gerar um URL do serviço (e.g., https://dataplex-agent-xyz.run.app). Clique nesse link para abrir a interface do chat de IA generativa totalmente controlada.

12a5fa4c2aaf381f.png

Fluxo arquitetônico completo

Você concluiu o sistema. Quando um usuário interage com a interface do ADK, ocorre a seguinte sequência:

  1. O usuário envia um comando no agente do ADK (interface de desenvolvimento).
  2. O agente do ADK (agent.py) processa a entrada e chama o modelo Gemini.
  3. O Gemini determina que precisa de contexto e pede ao servidor MCP para executar as ferramentas do Dataplex.
  4. O servidor MCP aplica as regras de governança do Dataplex e retorna os metadados.
  5. O Gemini sintetiza a resposta confiável com base nos metadados e a retorna ao usuário.

5. Testar o agente empresarial

Agora que o agente está ativo, vamos revisar os cenários de governança testados anteriormente com a CLI. A lógica permanece a mesma, mas agora você está interagindo com o ADK Web Playground implantado, que visualiza o estado interno e as execuções de ferramentas.

  1. Orquestração:o agente do ADK (em execução no Cloud Run) recebe seu texto.
  2. Encaminhamento de ferramentas:o Gemini reconhece que sua pergunta exige contexto de dados e encaminha a solicitação para o servidor MCP.
  3. Verificação de governança:o servidor MCP (em execução em uma instância separada do Cloud Run) consulta o Dataplex para tipos de aspectos específicos.
  4. Síntese:os metadados relevantes são retornados ao Gemini para gerar a resposta final.

Verificar a lógica de governança

Abra o URL do serviço que você gerou na etapa anterior (e.g., https://dataplex-agent-xyz.run.app) no seu navegador. Cole o seguinte comando:

"My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?"

Observe o processo de raciocínio do agente na interface do desenvolvedor:

  1. Reconhecimento de intenção:o agente analisa "agora mesmo" e "não posso esperar até amanhã".
  2. Pesquisa de metadados:chama a ferramenta MCP search_aspect_types. Ele procura recursos de dados em que o aspecto update_frequency está definido como REALTIME ou STREAMING, em vez de DAILY ou MONTHLY.
  3. Seleção:ela identifica que a tabela mkt_realtime_campaign_performance atende a esses critérios, enquanto fin_monthly_closing_internal (apesar de ser de alta qualidade) é muito lenta para sua solicitação.
  4. Resposta:o agente recomenda a tabela em tempo real.

e0da615724199e.png

Por que isso é importante:

Sem esses metadados de governança, um LLM provavelmente recomendaria a tabela fin_monthly_closing_internal simplesmente porque ela tem uma coluna chamada "ad_spend", ignorando o fato de que os dados têm 24 horas. O contexto dos metadados evitou um erro comercial.

Você também pode testar o comando "Reunião do conselho" para ver como o agente muda para diferentes tabelas com base no aspecto "Nível do produto de dados":

"We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?"

6. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste codelab, siga estas etapas para destruir toda a infraestrutura criada na Parte 1 e na Parte 2.

Destruir o data lake (Terraform)

Use o Terraform para desmontar as tabelas e os conjuntos de dados do BigQuery e as definições de aspectos do Dataplex.

cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

Excluir serviços do Cloud Run

Remova os recursos de computação para interromper o faturamento ativo dos contêineres em execução.

gcloud run services delete governance-mcp --region=$REGION --quiet
gcloud run services delete dataplex-agent --region=$REGION --quiet

Limpar artefatos de build e armazenamento de staging

Quando você implantou o agente do ADK usando uvx, o sistema criou automaticamente uma imagem de contêiner e fez upload do código-fonte para um bucket temporário do Cloud Storage. Esses artefatos permanecem mesmo depois que o serviço do Cloud Run é excluído e geram custos de armazenamento contínuos.

Remova o repositório do Artifact Registry e o bucket de preparo do Cloud Storage:

# Delete the repository used for the agent build
gcloud artifacts repositories delete cloud-run-source-deploy \
    --location=$REGION \
    --quiet

# Delete the staging bucket created by Cloud Run source deploy
gcloud storage rm --recursive gs://run-sources-${PROJECT_ID}-${REGION}

Excluir identidade, permissões e secrets

Remova primeiro as vinculações da política do IAM para evitar que entradas "tombstone" (registros órfãos) permaneçam na página do IAM do projeto. Em seguida, exclua as contas de serviço e os secrets de configuração.

# Remove IAM roles granted to the MCP Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/secretmanager.secretAccessor" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$MCP_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Remove IAM roles granted to the Agent Service Account
gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user" --quiet

# Delete the Service Accounts
gcloud iam service-accounts delete $MCP_SERVICE_ACCOUNT --quiet
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --quiet

# Delete the Secret Manager entry
gcloud secrets delete dataplex-tools-config --quiet

Remover configuração local

Por fim, limpe os arquivos de configuração local e as variáveis de ambiente no Cloud Shell.

# Uninstall the Gemini CLI extension (installed in Part 1)
gemini extensions uninstall dataplex

# Remove local repository files and unset variables
cd ~
rm -rf ~/devrel-demos
unset MCP_SERVER_URL
unset MCP_SERVICE_ACCOUNT
unset AGENT_SERVICE_ACCOUNT

7. Parabéns!

Você implantou um agente de IA generativa completo e com reconhecimento de governança.

Neste codelab de duas partes, você foi além da engenharia de comandos simples para implementar uma arquitetura robusta e pronta para produção. Ao tratar a governança de dados como um pré-requisito para a IA generativa, você estabeleceu um método sistemático para impedir que o modelo recupere dados não certificados ou alucinados.

Conclusões importantes

  • IA determinística usando metadados:em vez de confiar no LLM para adivinhar a tabela correta com base nos nomes das colunas, você aplicou um loop de raciocínio estrito usando a caixa de ferramentas de IA generativa para bancos de dados. Ao expor explicitamente apenas três ferramentas do Dataplex (search_aspect_types, search_entries, lookup_entry), você forçou o modelo a verificar as certificações de dados antes de sintetizar as respostas.
  • Arquitetura desacoplada (MCP): ao implantar o servidor do Protocolo de Contexto de Modelo (MCP) no Cloud Run, você abstraiu suas regras de governança de dados em uma API centralizada e padronizada. O agente de front-end não precisa conter lógica de banco de dados, apenas se comunicar pelo padrão MCP. Isso significa que você pode conectar qualquer modelo ou cliente de IA futuro ao mesmo back-end controlado.
  • Separação de funções:você aplicou o princípio do privilégio mínimo isolando as identidades do IAM. O agente do ADK voltado ao usuário opera com permissões restritas à invocação de modelos e ao roteamento de API, enquanto o servidor MCP de back-end processa com segurança consultas de catálogo do Dataplex e recuperação de dados do BigQuery.
  • Orquestração de agentes com prioridade ao código:você usou o Kit de Desenvolvimento de Agente (ADK) do Google para encapsular instantaneamente a lógica do agente Python em um back-end FastAPI escalonável, usando a interface do desenvolvedor integrada para visualizar e depurar as execuções de ferramentas internas do agente.

A seguir