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 com reconhecimento de governança.

Leia a primeira parte desta série, que aborda como estabelecer a base de dados registrando um tipo de aspecto do Knowledge Catalog, aplicando aspectos a tabelas do BigQuery e testando as regras localmente usando a CLI do AGY. 👉 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. Em vez de implantar um servidor MCP personalizado, você vai conectar seu agente diretamente ao servidor MCP do Knowledge Catalog gerenciado pelo Google. Em seguida, você vai usar o Kit de Desenvolvimento de Agente (ADK) do Google para criar o aplicativo de agente, carregar as regras de governança da habilidade do agente local e implantá-lo no Cloud Run, com uma interface da Web profissional.

.

Quando um usuário interage com a interface do ADK, a seguinte sequência ocorre:

8912d1983c34ee8e.png

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 o agente do ADK se conecta ao servidor MCP do Knowledge Catalog gerenciado pelo Google.
  • Como carregar suas regras de governança de forma dinâmica na habilidade do agente compartilhado.
  • Como implantar o agente no Cloud Run e executar o playground da Web integrado do ADK.

O que é necessário

  • Ter um projeto do Google Cloud com o faturamento ativado.
  • Acesso ao Google Cloud Shell.
  • 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 Knowledge Catalog criados na Parte 1. Não se preocupe se você os excluiu. Abaixo, fornecemos um script rápido para recriá-los.

Principais conceitos

  • 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 empresariais, como o Knowledge Catalog e o BigQuery.
  • Kit de Desenvolvimento de Agente (ADK): um framework flexível de código aberto do Google projetado para simplificar o desenvolvimento completo 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.
  • Gemini Enterprise Agent Platform(GEAP):o ambiente de hospedagem e orquestração de nível empresarial para implantação de agentes de IA no Google Cloud.

2. Configuração e requisitos

Iniciar 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"

Ativar APIs obrigatórias

Ative o conjunto mínimo de APIs do Google Cloud necessárias para gerenciar sua base de dados, executar modelos da Vertex AI e hospedar o agente do ADK no Cloud Run.

gcloud services enable \
    dataplex.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Checkpoint: retomar ou reconstruir?

Como esta é a Parte 2, seu agente precisa dos dados controlados 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 concluída)

Sem problemas. Fornecemos um bloco de comandos de "Fast-Track" abaixo. Isso vai recriar automaticamente o data lake do BigQuery, registrar o tipo de aspecto e aplicar os metadados de governança 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 BigQuery datasets and tables
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

# 3. Register the Knowledge Catalog aspect type
gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --metadata-template-file-name="aspect_template.json"

# 4. Generate and apply aspects (governance rules)
chmod +x ./generate_payloads.sh ./apply_governance.sh
./generate_payloads.sh
./apply_governance.sh

3. O plano de controle de dados centralizado (MCP gerenciado)

Em um ambiente empresarial real, você precisa de um plano de controle de dados seguro e centralizado. Em vez de criar e implantar um contêiner de servidor MCP personalizado no Cloud Run, vamos conectar nosso agente diretamente ao servidor MCP do catálogo de conhecimento gerenciado pelo Google.

Ao usar esse endpoint gerenciado, conseguimos:

  1. Manutenção zero:não é necessário gerenciar contêineres, escalonamento ou patches para o servidor MCP.
  2. Padronização:o agente se conecta a um endpoint de API padrão e seguro do Google usando o Protocolo de Contexto de Modelo (transporte SSE).
  3. Escopo controlado:o servidor MCP expõe apenas as ferramentas de metadados necessárias (search_entries, lookup_context, lookup_entry), aplicando um loop de raciocínio somente leitura e com foco na governança.

O servidor MCP do Knowledge Catalog gerenciado pelo Google pode ser acessado pelo seguinte URL seguro:

https://dataplex.googleapis.com/mcp

Como essa é uma API do Google de terceiros, o agente precisa fazer a autenticação usando um token de acesso OAuth2 padrão do Google Cloud em vez de um token de ID. Vamos processar essa autenticação automaticamente no código do aplicativo.

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

Você tem um plano de controle de dados gerenciado e seguro. 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.

Vamos usar o Kit de Desenvolvimento de Agente (ADK) do Google. O ADK é um framework que prioriza o código e envolve automaticamente a lógica do agente em um back-end do FastAPI, além de fornecer uma interface da Web integrada para testes instantâneos.

Abra o código do agente no editor do Cloud Shell

Em vez de despejar todo o arquivo no terminal, vamos abri-lo no editor do Cloud Shell para que você possa inspecionar, editar e entender o código com facilidade.

Execute o comando abaixo no terminal e observe a estrutura do código no editor. O aplicativo é criado usando o Kit de Desenvolvimento de Agente (ADK) do Google:

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

# Copy the governance skill directory inside the application bundle so it packages during Cloud Run deployment
mkdir -p skills
cp -r ../.agents/skills/knowledge-catalog-governance skills/

cloudshell edit agent.py

Observação: agent.py contém código boilerplate na parte de cima para processar a autenticação OAuth2 do Google Cloud e a atualização de tokens, garantindo que o agente possa se comunicar com segurança com a API Knowledge Catalog gerenciada pelo Google.

1. Carregamento de habilidades nativas

Para criar um agente altamente otimizado, carregamos as instruções de governança do diretório de habilidades do agente externo usando o load_skill_from_dir nativo do ADK. Essa abordagem permite a divulgação progressiva:

  • Metadados de nível 1:o agente carrega apenas o nome e a descrição da habilidade na inicialização. Esse contexto mínimo permite que o LLM identifique quando usar a habilidade sem consumir grandes quantidades de tokens antecipadamente.
  • Instruções de nível 2:o conjunto completo de instruções em SKILL.md é buscado dinamicamente no tempo de execução somente quando o modelo determina que ele é relevante.
base_dir = Path(__file__).parent
governance_skill = load_skill_from_dir(
    base_dir / "skills" / "knowledge-catalog-governance"
)

# Bundle the skill and MCP tools together into a SkillToolset
governance_skill_toolset = skill_toolset.SkillToolset(
    skills=[governance_skill],
    additional_tools=[tools]
)

2. Orquestração de agentes

Com o ADK, é possível orquestrar comportamentos complexos de agentes encadeando vários deles. Definimos um fluxo de trabalho SequentialAgent composto por dois agentes especializados:

  • governance_researcher: Equipado com governance_skill_toolset e o MCP do Knowledge Catalog tools. Ele verifica se a consulta está dentro do catálogo de dados e do escopo de compliance e consulta o Knowledge Catalog usando variáveis de ambiente injetadas nas instruções do sistema.
  • compliance_formatter: Responsável por traduzir os resultados brutos da pesquisa de metadados JSON em uma resposta limpa ou explicar os limites do escopo se a solicitação estiver fora do escopo.
# 1. Researcher Agent (has access to the encapsulated SkillToolset)
governance_researcher = LlmAgent(
    name="governance_researcher",
    model=model_name,
    description="Dynamically interprets metadata schema (Booleans/Enums) and searches for assets using strict syntax.",
    instruction=f"""
    You are a governance researcher. Your job is to verify Knowledge Catalog metadata rules and find compliant assets for the user's query.
    
    YOUR ACTIVE ENVIRONMENT CONTEXT:
    - Google Cloud Project ID: {project_id}
    - Location (Region): {location}

    YOUR WORKFLOW:
    1. First, check if the user query is related to data analytics assets, database tables, or data compliance.
       - If YES: Call `load_skill` with `name="knowledge-catalog-governance"` to load the rules, then use search/lookup tools to locate a certified compliant table.
       - If NO (e.g., general chit-chat, unrelated tasks): Skip skill loading and output a JSON object indicating it is out of scope:
         {"error": "out_of_scope", "message": "The query does not pertain to data catalog search or governance compliance."}
    2. Populate the required projectId and location parameters in tool calls with the active environment parameters.
    3. Return the verified table's metadata in JSON format as your final research output.
    """,
    tools=[governance_skill_toolset, tools],
    output_key="research_data"
)

# 2. Formatter Agent (formats the output or explains out-of-scope errors)
compliance_formatter = LlmAgent(
    name="compliance_formatter",
    model=model_name,
    description="Formats the JSON research data into a helpful response for the user.",
    instruction="""
    You are the **Intelligent Data Governance Specialist**.
    Your job is to explain the findings of the governance research clearly to the user.

    **YOUR GOAL:**
    1. If the researcher found a matching table (valid JSON with table metadata):
       - Explain the logical connection between the User's Request, the Governance Schema (translated criteria), and the Recommended Table.
       - Use the following RESPONSE TEMPLATE:
         - **Analysis:** "I analyzed the metadata schema and translated your request into the following technical criteria:..."
         - **Recommendation:** "Based on this, I recommend the following table:"
           - **Table:** [Insert Table Name]
           - **Description:** [Insert Table Description]
         - **Verification:** "This asset is a verified match because: [Explain the verification details]."
    2. If the researcher returned an 'out_of_scope' error or no matching tables were found:
       - Apologize politely and explain that no data asset currently matches the strict governance criteria defined in `official-data-product-spec`.
       - Clearly state what domain of questions this agent is certified to answer (e.g., Data Catalog Search and Data Governance compliance).
    """
)

# 3. Orchestrated Workflow (Exported as root_agent)
root_agent = SequentialAgent(
    name="governance_workflow",
    description="Workflow to learn metadata rules, search with strict syntax, and recommend assets.",
    sub_agents=[
        governance_researcher,
        compliance_formatter,
    ]
)

Configurar variáveis de execução

Para executar o agente, precisamos informar onde o servidor MCP gerenciado está localizado e configurar o projeto e a região dele. Vamos salvar essas variáveis em um arquivo .env que o ADK vai ler durante a execução.

Execute o comando a seguir para gerar o arquivo .env. O MCP_SERVER_URL aponta diretamente para o endpoint da API Knowledge Catalog gerenciado pelo Google:

export MCP_SERVER_URL="https://dataplex.googleapis.com/mcp"

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

5. Executar e testar o agente localmente

Antes de implantar o agente na nuvem, execute-o localmente no Cloud Shell para verificar o comportamento dele. Como o agente depende de vários pacotes Python (incluindo as bibliotecas do Google Cloud Logging e do ADK), vamos configurar um ambiente virtual local para instalar essas dependências.

Ao executar localmente no Cloud Shell, o agente usa automaticamente suas credenciais de usuário ativas do Google Cloud. Assim, ele já tem as permissões necessárias para acessar a Vertex AI e o Knowledge Catalog.

  1. Navegue até o diretório mcp_server, crie um ambiente virtual e instale as dependências:
cd ~/devrel-demos/data-analytics/governance-context/mcp_server

# Create a virtual environment using uv
uv venv
source .venv/bin/activate

# Install the dependencies listed in requirements.txt
uv pip install -r requirements.txt
  1. Inicie a sessão de chat interativa no terminal:
adk run .
  1. Quando a sessão começar, você vai receber uma solicitação. Digite uma consulta para testar a lógica de governança do agente:
I need the Q1 revenue summary for our internal board meeting.

O agente vai processar sua solicitação, consultar o Knowledge Catalog usando o servidor MCP gerenciado e gerar a recomendação e o raciocínio diretamente no terminal.

  1. Para sair da sessão interativa, digite exit ou quit (ou pressione Ctrl+C). Depois de sair, desative o ambiente virtual:
deactivate

6. Implantar o agente na produção

Agora que você verificou o agente localmente, está pronto para implantá-lo no Google Cloud para uso em produção.

Criar uma conta de serviço

Por segurança, o agente implantado não deve ser executado com suas credenciais pessoais. Vamos criar uma identidade separada (knowledge-catalog-agent-sa) para o agente, seguindo o princípio de privilégio mínimo.

Execute os seguintes comandos para criar a conta de serviço:

export AGENT_SA=knowledge-catalog-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 Knowledge Catalog Agent"

Conceder permissões

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

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogAdmin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/viewer"

Implantar no Cloud Run

Por fim, implante o agente no Cloud Run. O comando a seguir cria a imagem do contêiner usando o Dockerfile no diretório atual, faz upload para o Artifact Registry e implanta no Cloud Run. Esse processo pode levar de 1 a 3 minutos.

gcloud run deploy knowledge-catalog-agent \
  --source . \
  --project=$PROJECT_ID \
  --region=$REGION \
  --service-account=$AGENT_SERVICE_ACCOUNT \
  --allow-unauthenticated \
  --clear-base-image \
  --labels created-by=adk

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

12a5fa4c2aaf381f.png

7. Testar o atendente

Agora que seu agente está ativo, vamos testar os cenários de governança. 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.

Abra o URL do serviço gerado na etapa anterior (por exemplo, https://knowledge-catalog-agent-xyz.run.app) no 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 para desenvolvedores:

  1. Reconhecimento de intenção:o agente analisa "agora mesmo" e "não posso esperar até amanhã".
  2. Pesquisa de metadados:chama a ferramenta search_entries do MCP com a consulta: [PROJECT_ID].us-central1.official-data-product-spec.update_frequency=REALTIME_STREAMING
  3. Seleção:identifica que a tabela mkt_realtime_campaign_performance atende a esses critérios.
  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?"

8. Limpar

Para evitar cobranças na sua conta do Google Cloud, siga estas etapas para destruir toda a infraestrutura criada neste codelab.

Destruir o data lake

Use o script de limpeza para desativar as tabelas e os conjuntos de dados do BigQuery e as definições de aspectos do Knowledge Catalog.

cd ~/devrel-demos/data-analytics/governance-context
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

Excluir serviços do Cloud Run

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

gcloud run services delete knowledge-catalog-agent --region=$REGION --quiet

Limpar artefatos de build e armazenamento de preparo

Quando você implantou o agente do ADK, o sistema criou automaticamente uma imagem de contêiner e fez upload do código-fonte para um bucket temporário do Cloud Storage.

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 e permissões

Remova as vinculações da política do IAM primeiro e depois exclua as contas de serviço.

# 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

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/dataplex.catalogViewer" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/mcp.toolUser" --quiet

gcloud projects remove-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$AGENT_SERVICE_ACCOUNT" \
  --role="roles/bigquery.dataViewer" --quiet

# Delete the Service Account
gcloud iam service-accounts delete $AGENT_SERVICE_ACCOUNT --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 AGY CLI plugin
agy plugin uninstall dataplex

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

9. Parabéns!

Você implantou um agente de IA generativa completo e com 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.

Pontos principais

  • IA determinista com metadados:em vez de confiar no LLM para adivinhar a tabela correta com base nos nomes das colunas, você impôs um loop de raciocínio estrito usando o servidor MCP do Knowledge Catalog gerenciado pelo Google, forçando o modelo a verificar as certificações de dados antes de recomendar tabelas.
  • Arquitetura desacoplada:o agente de front-end não precisa conter lógica de banco de dados. Ele só precisa se comunicar pelo padrão MCP. Isso significa que você pode conectar qualquer modelo ou cliente de IA futuro ao mesmo back-end controlado.
  • Segregação de funções:você aplicou o princípio de 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.
  • Orquestração de agentes com foco no 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