Agente de ciência de dados com estado no Agent Runtime

1. Visão geral

Neste codelab, você vai criar um agente de ciência de dados que consulta dados reais de conjuntos de dados públicos do BigQuery e se lembra das suas preferências em várias sessões. Em seguida, você vai implantar no Agent Runtime, um serviço totalmente gerenciado do Google Cloud que lida com infraestrutura, escalonamento e gerenciamento de sessão.

O agente usa três recursos principais que são ativados progressivamente:

• Conjunto de ferramentas do BigQuery: o agente explora esquemas e executa consultas SQL em conjuntos de dados reais do BigQuery. Isso funciona localmente e quando implantado.
• Memory Bank: quando implantado, o agente lembra as preferências e o contexto do usuário em sessões desconectadas.
• Observabilidade: o Cloud Trace captura as etapas de raciocínio, as chamadas de ferramentas e as latências do agente usando a instrumentação do OpenTelemetry.

O que você vai aprender

• Como criar um agente do ADK com BigQueryToolset para acesso aos dados reais
• Como configurar o Memory Bank para persistência entre sessões
• Como implantar seu agente no Agent Runtime com adk deploy
• Como conceder permissões do IAM à conta de serviço do agente implantado
• Como testar a persistência e a observabilidade da memória

O que é necessário

• Tenha um projeto do Google Cloud com o faturamento ativado.
• Um navegador da web, como o Chrome
• Se você executar o código na sua própria máquina em vez do Cloud Shell: o SDK do Google Cloud (CLI gcloud), o uv (gerenciador de pacotes do Python) e o Python 3.12 ou mais recente (instalado automaticamente pelo uv, se necessário).

O ADK (Kit de Desenvolvimento de Agente) é o framework do Google para criar agentes de IA. Este codelab usa o ADK para criar um agente e implantá-lo no Agent Runtime.

Este codelab é destinado a desenvolvedores intermediários que têm alguma familiaridade com Python e o Google Cloud.

Este codelab leva aproximadamente 35 minutos para ser concluído, incluindo de 5 a 10 minutos para a implantação.

Os recursos criados neste codelab custam menos de US $5.

2. Configurar o ambiente

Criar um projeto do Google Cloud

1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem 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.

Definir o projeto

Abra o editor do Cloud Shell no projeto do GCP criado.

Em seguida, crie um Terminal > Novo terminal e execute o seguinte comando para definir seu projeto. Os comandos posteriores leem o ID do projeto dessa configuração.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Ativar APIs

No terminal, execute o seguinte comando:

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com: hospeda seu agente no Agent Runtime, incluindo sessões e Memory Bank do Gemini Enterprise, e veicula o modelo do Gemini
• API BigQuery (bigquery.googleapis.com): consultas SQL em conjuntos de dados públicos e particulares
• API Telemetry (telemetry.googleapis.com): rastreamentos do OpenTelemetry para observabilidade do agente

A ativação da API pode levar até um minuto para ser propagada. Se você encontrar erros de "API não ativada" nas etapas posteriores, aguarde um momento e tente de novo.

Instale o ADK

No terminal, execute os comandos a seguir para criar uma pasta para este codelab e instalar o ADK e as dependências dele:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

O uv cria um ambiente Python isolado para este codelab, então você não precisa ativar nada. Adicione o prefixo uv run aos comandos do Python.

O pacote google-adk inclui a ferramenta de linha de comando adk, que você vai usar para testar e implantar o agente. O adk deploy usa o google-cloud-aiplatform para criar seu agente no Agent Runtime, e o google-cloud-bigquery é a biblioteca de cliente por trás das ferramentas do BigQuery do ADK.

3. Criar o agente

Na pasta ~/adk-deploy-scale, crie o diretório do agente. Execute todos os comandos posteriores em ~/adk-deploy-scale (o pai de data_science_agent/):

mkdir data_science_agent

Em seguida, execute o comando a seguir para criar o data_science_agent/.env com seu projeto, a região em que você vai implantar o agente e as configurações do agente implantado. O adk deploy lê esse arquivo, então essas configurações ainda funcionam se você abrir um novo terminal.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT e GOOGLE_CLOUD_LOCATION: o ID do projeto (preenchido com base em gcloud) e a região em que o agente é executado
• GOOGLE_GENAI_USE_ENTERPRISE: fez uma chamada da ADK para o Gemini usando seu projeto na nuvem do Google Cloud.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: registra entradas de comandos completas e respostas do agente, o que é útil para depuração.

A configuração OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT registra o conteúdo completo dos comandos do usuário e das respostas do agente no Cloud Logging. Isso é útil para depuração, mas pode capturar dados sensíveis ou PII. Em produção, defina isso como false ou verifique se você tem políticas adequadas de tratamento de dados.

A estrutura de diretórios final vai ficar assim:

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

Você vai criar __init__.py e agent.py agora e adicionar requirements.txt na etapa de implantação.

Crie data_science_agent/__init__.py. Esse arquivo é necessário para que o ADK possa descobrir e carregar seu agente:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

Crie data_science_agent/agent.py:

Esse agente se conecta ao BigQuery para extração de dados e mantém as sessões no Memory Bank.

A memória é ativada automaticamente quando implantada. O ambiente de execução do agente define a variável de ambiente GOOGLE_CLOUD_AGENT_ENGINE_ID, que não está presente ao executar localmente.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by Agent Runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Runtime, where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model=Gemini(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

Vamos analisar o que esse código faz:

1. O BigQueryToolset oferece ao agente ferramentas como execute_sql, list_table_ids e get_table_info. Ele pode analisar esquemas e consultar qualquer conjunto de dados a que o usuário tenha acesso.
2. A PreloadMemoryTool recupera automaticamente memórias relevantes antes de cada chamada de LLM pesquisando no banco de memória conteúdo relacionado à mensagem do usuário. O callback _save_memory mantém a sessão no Memory Bank após cada execução do agente, para que ele possa se lembrar do contexto em sessões futuras.
3. O App encapsula o agente raiz em um aplicativo implantável que o Agent Runtime pode disponibilizar. O name precisa corresponder ao nome do diretório (data_science_agent). O adk web usa isso para localizar e carregar o agente.
4. A instrução informa ao agente para usar o projeto de faturamento em consultas SQL e lembrar das preferências do usuário.
5. O Gemini com client_kwargs={"location": "global"} envia chamadas de modelo para o endpoint global, onde o gemini-3.8-flash está disponível. O agente é executado em us-central1: adk deploy define GOOGLE_CLOUD_LOCATION no agente implantado para a região em que você faz a implantação. Assim, a localização do modelo é definida no código.

4. implantar no Agent Runtime

Crie um arquivo requirements.txt no diretório data_science_agent:

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk e google-genai: ADK e o cliente do Gemini
• google-auth: autenticação do Google Cloud
• google-cloud-bigquery: a biblioteca de cliente do BigQuery usada por BigQueryToolset. O ADK não o instala por padrão.
• python-dotenv: carrega o arquivo .env na inicialização
• Os três pacotes opentelemetry-instrumentation-* ativam os recursos de observabilidade que você vai conhecer mais tarde. Eles instrumentam chamadas de modelo do Gemini e comunicação interna gRPC/HTTP para que os rastreamentos apareçam na guia Rastreamentos do seu agente.

Não adicione google-cloud-aiplatform ao seu requirements.txt, mesmo que você o tenha instalado localmente. O adk deploy adiciona isso para você (junto com a versão do ADK que você implanta), mas apenas quando o requirements.txt ainda não o lista. Declarar isso por conta própria pode causar conflitos de versão de pacote do OpenTelemetry que interrompem silenciosamente a instrumentação, fazendo com que os rastreamentos não apareçam na guia "Traces".

O adk deploy também lê o arquivo data_science_agent/.env criado anteriormente e define as configurações dele no agente implantado.

Implante o agente. O último argumento data_science_agent é o diretório que contém o código do agente:

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

Perto do início, a saída mostra duas linhas amarelas, Ignoring GOOGLE_CLOUD_PROJECT in .env ... e Ignoring GOOGLE_CLOUD_LOCATION in .env .... Isso é esperado: as flags --project e --region têm precedência sobre os mesmos valores em .env.

Sinalização	Finalidade
--project / --region	Projeto na nuvem e região de destino do Google Cloud
--display_name	Nome legível mostrado no console do Cloud.
--otel_to_cloud	Exporta traces e registros do OpenTelemetry para o Google Cloud e ativa a telemetria (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) no agente implantado.

A implantação geralmente leva de 5 a 10 minutos. Quando concluída, a saída mostra o nome do recurso do agente (projects/.../reasoningEngines/) e um link para visualizá-lo no console do Cloud.

Enquanto espera, consulte os documentos do Memory Bank para saber mais sobre como funciona a memória entre sessões.

Se o link impresso por adk deploy não funcionar, abra a página "Implantações" no console do Cloud e clique no seu agente.

Quando implantadas no Agent Runtime, duas funcionalidades são ativadas automaticamente:

• Memory Bank: o adk deploy conecta o agente às Sessões e ao Memory Bank na instância do Agent Runtime. O PreloadMemoryTool lê do Memory Bank, e o _save_memory persiste as sessões automaticamente.
• Observabilidade: o Cloud Trace captura as etapas de raciocínio, as chamadas de ferramentas e as latências do agente.

5. Conceder permissões do BigQuery

É necessário conceder ao BigQuery acesso ao agente de serviço do Agent Runtime (o agente de serviço do mecanismo de inferência da AI Platform). Quando implantado, o agente é executado como essa conta de serviço gerenciada pelo Google (não suas credenciais pessoais). Por isso, ele precisa de permissões explícitas para executar consultas SQL.

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get project) \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

Cada comando imprime Updated IAM policy for project [...] quando é executado corretamente.

Se você pular esta etapa, o agente implantado vai retornar erros 403 ao executar consultas SQL. A função bigquery.jobUser é necessária no projeto de faturamento (seu projeto), e não no projeto de dados.

Observação: bigquery.dataViewer concede acesso de leitura a todos os conjuntos de dados no seu projeto. Para uso em produção, considere conceder esse papel no nível do conjunto de dados.

6. Testar o agente implantado

Abra a página "Implantações" no console do Google Cloud. Clique no agente implantado e na guia Playground.

Cada consulta pode levar de 10 a 30 segundos para ser concluída enquanto o agente raciocina, chama ferramentas e retorna resultados.

Teste os recursos do BigQuery:

1. "Liste as tabelas em bigquery-public-data.hacker_news"
   • Esperado: o agente chama list_table_ids e retorna nomes de tabelas, incluindo full.
2. "Encontre o número de postagens por ano em bigquery-public-data.hacker_news.full"
   • Esperado: o agente chama execute_sql com uma consulta SQL e retorna uma tabela de anos e contagens de postagens.
3. "Qual foi a mudança percentual ano a ano nas postagens?"
   • Esperado: o agente chama execute_sql com uma consulta SQL que calcula a mudança percentual e retorna os resultados.

7. Testar a persistência da memória

Ainda no playground, ensine uma preferência ao agente:

1. "Lembre-se de que meu conjunto de dados favorito é bigquery-public-data.hacker_news"
2. "Quais tabelas ele tem?"

Aguarde alguns segundos para que a memória persista. O callback _save_memory é executado depois que o agente responde.

Agora, inicie uma nova sessão clicando em Nova sessão no Playground e faça a seguinte pergunta:

3. "Qual é meu conjunto de dados favorito?"

O agente precisa se lembrar de bigquery-public-data.hacker_news, mesmo que seja uma sessão totalmente nova sem histórico de conversa. Isso funciona porque:

• _save_memory persiste cada sessão no Memory Bank usando callback_context.add_session_to_memory()
• PreloadMemoryTool recupera memórias relevantes antes de cada chamada de LLM
• O Memory Bank faz correspondências semânticas de conteúdo, não apenas por palavra-chave

Se o agente não se lembrar da sua preferência, aguarde 10 segundos e tente de novo em outra sessão. A persistência de memória é assíncrona e pode levar um tempo para ser concluída.

8. Conheça a observabilidade

No console do Cloud, navegue até o agente implantado e clique na guia Rastreamentos.

Uma tabela de sessões vai aparecer com as sessões das consultas de teste executadas nas etapas anteriores. A tabela mostra métricas de resumo para cada sessão: duração média, chamadas de modelo e de ferramentas, uso de tokens e erros.

Clique em uma sessão para inspecionar os detalhes do trace, incluindo:

• Um gráfico acíclico direcionado (DAG) dos intervalos, mostrando o detalhamento das etapas do raciocínio do agente, das chamadas de ferramentas (consultas do BigQuery) e das latências.
• Entradas e saídas para cada intervalo (ativado pela variável de ambiente OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT em .env)
• Atributos de metadados, como IDs de extensão, IDs de rastreamento e tempo

Você também pode mudar para a visualização de período (alternância na parte de cima) para conferir períodos individuais em todas as sessões.

Os rastreamentos podem levar de 1 a 2 minutos para aparecer após a conclusão de uma consulta. Se você ainda não encontrar nenhum rastreamento, aguarde um momento e atualize a página.

Como o rastreamento funciona

Ao implantar com --otel_to_cloud, o adk deploy cria um contêiner que executa o servidor de API do ADK com o OpenTelemetry ativado. No Agent Runtime, o servidor inicializa um pipeline do OpenTelemetry que:

1. Cria um TracerProvider com um exportador OTLP que envia períodos para telemetry.googleapis.com
2. Registra os próprios intervalos do ADK para execuções de agentes, chamadas de modelo e chamadas de ferramentas, além de usar os três pacotes de instrumentação do seu requirements.txt para adicionar intervalos de bibliotecas principais (Gemini, httpx, gRPC).
3. Agrupa e exporta intervalos para a API Telemetry, onde a guia "Rastreamentos" os lê.

O contêiner implantado inclui o ADK e o SDK e exportador do OpenTelemetry, mas não inclui os pacotes de instrumentação. Por isso, o requirements.txt lista os três. Sem eles, o servidor da API ADK registra um aviso e pula esses intervalos.

Solução de problemas

Se nenhum rastreamento aparecer após alguns minutos:

1. Verifique se a API Telemetry está ativada: você a ativou na etapa de configuração. Verificar com: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. Verificar avisos no Cloud Logging: acesse Logging > Análise de registros e pesquise "proceeding without" ou "GoogleGenAiSdkInstrumentor". Um aviso que nomeia uma instrumentação (GenAI, HTTPX ou gRPC) significa que o pacote opentelemetry-instrumentation-* correspondente está faltando no seu requirements.txt.
3. Não adicione google-cloud-aiplatform ao seu requirements.txt. O adk deploy adiciona automaticamente. Declarar por conta própria pode causar conflitos de pacotes do OpenTelemetry e interromper a instrumentação sem aviso.

9. Limpeza

Para evitar cobranças contínuas, exclua os recursos criados durante este codelab.

Exclua o agente implantado na página "Implantações" no console do Cloud. Selecione seu agente e clique em Excluir.

As consultas do BigQuery neste codelab usaram conjuntos de dados públicos, que não geram cobranças de armazenamento. Os papéis do IAM concedidos permanecem no projeto, mas não têm impacto no custo.

Se você criou um projeto especificamente para este codelab, exclua o projeto inteiro:

gcloud projects delete <YOUR_PROJECT_ID>

Opcional: limpe o ambiente local:

cd ~
rm -rf ~/adk-deploy-scale

10. Parabéns

Você criou um agente de ciência de dados com estado e o implantou no Agent Runtime.

O que você aprendeu

• Como criar um agente do ADK com BigQueryToolset para acesso aos dados reais
• Como ativar a memória persistente com o Memory Bank usando PreloadMemoryTool e after_agent_callback
• Como conceder permissões do IAM à conta de serviço do agente implantado
• Como implantar no Agent Runtime e ativar a observabilidade com o Cloud Trace

Próximas etapas

• Consulte seus próprios conjuntos de dados particulares do BigQuery concedendo ao agente de serviço do Agent Runtime acesso aos seus dados
• Adicione a Execução de código para executar a análise do Python em um sandbox seguro
• Configure painéis de observabilidade do Cloud Trace para monitorar seu agente em produção.
• Publicar resultados no Google Workspace usando as ferramentas do MCP

Documentos de referência

• Documentação do ADK
• Documentação do Agent Runtime
• Documentação do Memory Bank
• Guia de implantação do Agent Runtime