Como criar agentes de IA com o ADK: agente de análise de dados

1. Antes de começar

LEIA:

Este tutorial requer um projeto do Google Cloud com uma conta de faturamento ativa.

Para participantes de workshops presenciais: siga as instruções específicas de configuração e faturamento fornecidas pelo instrutor.

Para usuários de autoaprendizagem: siga estas etapas para resgatar um teste:

• Abra uma janela anônima no navegador.
• Acesse este portal de resgate.
• Faça login usando sua conta pessoal do Gmail.
• Siga as instruções detalhadas do portal.

Esta é a quarta parte da série "Como criar agentes de IA com o ADK". Neste codelab prático, você vai combinar o que aprendeu nas sessões anteriores para criar um agente de análise de dados. Ele será projetado para analisar dados, gerar insights valiosos e automatizar aspectos importantes do fluxo de trabalho de análise de dados.

Você vai permitir que seu agente analise arquivos enviados e o conecte a bancos de dados empresariais, como o Google Cloud BigQuery, usando as ferramentas avançadas incluídas no ADK.

Você também pode acessar este codelab usando o URL encurtado: goo.gle/adk-data-analyst

Pré-requisitos

• Entendimento básico dos conceitos de IA generativa
• Conhecimentos básicos de programação em Python e familiaridade com o uso da linha de comando.
• Familiaridade com os conceitos dos codelabs anteriores desta série: "The Foundation" e "Empowering with Tools".

O que você vai aprender

• Como criar um agente de analista de dados funcional usando o framework ADK.
• Métodos para permitir que um agente analise dados de documentos enviados.
• Como conectar seu agente a um banco de dados do BigQuery para análise de dados em nível empresarial.
• Técnicas para definir a lógica principal do agente, incluindo propósito e instruções.

O que é necessário

• Um computador em funcionamento e uma conexão de Internet confiável.
• Um navegador, como o Chrome, para acessar o console do Google Cloud
• Uma mente curiosa e vontade de aprender.

2. Introdução

No mundo atual, orientado por dados, a capacidade de analisar rapidamente e com precisão grandes quantidades de informações é mais importante do que nunca. No entanto, o processo de extração de insights significativos geralmente exige um profundo conhecimento técnico em áreas como SQL, criando um gargalo que pode diminuir a velocidade da tomada de decisões. E se você pudesse diminuir essa distância e interagir com conjuntos de dados complexos com a mesma facilidade de uma conversa?

É aí que os agentes de IA estão mudando o jogo. Ao atuar como uma interface inteligente entre você e seus dados, os agentes de IA podem entender perguntas em linguagem natural, traduzi-las em consultas técnicas e fornecer insights úteis em segundos.

Neste codelab, você vai entrar no futuro da análise de dados criando um agente de analista de dados prático usando o Kit de Desenvolvimento de Agente (ADK). Vamos começar criando um agente básico e depois aprimorar progressivamente os recursos dele. Primeiro, você vai ensinar o agente a analisar dados não estruturados de documentos enviados. Em seguida, você vai conectar a um data warehouse corporativo eficiente, o Google Cloud BigQuery, para consultar e analisar um conjunto de dados de saúde em grande escala e do mundo real.

Ao final deste tutorial, você terá não apenas um assistente de IA funcional, mas também um entendimento sólido de como criar agentes que podem automatizar tarefas rotineiras de dados, acelerar a análise e democratizar o acesso a insights importantes para você e sua equipe.

3. Configurar serviços do Google Cloud

Criar um projeto na nuvem do Google Cloud

Para manter todo o seu trabalho neste codelab organizado e separado de outros projetos, comece criando um projeto na nuvem do Google.

1. Acesse console.cloud.google.com/projectcreate.
2. Insira as informações necessárias:

• Nome do projeto: você pode inserir qualquer nome que quiser (por exemplo, genai-workshop).
• Local: deixe como Nenhuma organização.
• Conta de faturamento: se essa opção aparecer, selecione "Conta de faturamento de teste do Google Cloud Platform" ou sua própria conta de faturamento, se preferir. Se essa opção não aparecer, prossiga para a próxima etapa.

3. Copie o ID do projeto gerado. Ele será necessário mais tarde.

4. Se tudo estiver certo, clique no botão Criar.

Configurar o Cloud Shell

Depois que o projeto for criado, siga estas etapas para configurar o Cloud Shell.

1. Iniciar o Cloud Shell

Acesse shell.cloud.google.com. Se aparecer um pop-up pedindo autorização, clique em Autorizar.

2. Definir ID do projeto

Substitua replace-with-your-project-id pelo ID do projeto da etapa de criação acima. Execute o seguinte comando no terminal do Cloud Shell para definir o ID do projeto correto.

gcloud config set project replace-with-your-project-id

Agora você vai ver que o projeto correto está selecionado no terminal do Cloud Shell. O ID do projeto selecionado é destacado em amarelo.

3. Ativar as APIs necessárias

Para usar os serviços do Google Cloud, primeiro é necessário ativar as APIs respectivas no seu projeto. Execute os comandos abaixo no terminal do Cloud Shell para ativar os serviços deste codelab:

gcloud services enable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

Se a operação for bem-sucedida, você verá a mensagem Operation/... finished successfully impressa no terminal.

4. Crie um ambiente virtual em Python.

Em seguida, crie um ambiente Python isolado para gerenciar as dependências do projeto.

Observação:vamos usar uv para criar nosso ambiente virtual em vez do pacote padrão venv. É um gerenciador de projetos e pacotes Python incrivelmente rápido escrito em Rust.

Se quiser saber mais, confira a documentação oficial do uv (link em inglês).

1. Crie um diretório de projeto e navegue até ele:

mkdir -p ai-agents-adk && cd ai-agents-adk

2. Crie e ative um ambiente virtual:

uv venv --python 3.12
source .venv/bin/activate

O prefixo (ai-agents-adk) vai aparecer no comando do terminal, indicando que o ambiente virtual está ativo.

3. Página de instalação do ADK

uv pip install google-adk --no-cache

Observação:se você fechar o terminal por engano, acesse a pasta ai-agents-adk e execute source .venv/bin/activate novamente.

5. Criar um agente inicial

Com o ambiente pronto, é hora de criar seu agente de IA usando um comando simples do ADK.

1. Criar um agente

No terminal, execute o seguinte comando:

adk create data_analyst_agent

2. Configure seu agente

Você vai precisar configurar seu agente. Faça as seguintes seleções:

• Escolha um modelo: selecione 1. gemini-2.5-flash.
• Escolha um back-end: selecione 2. Vertex AI.
• Insira o ID do projeto na nuvem do Google Cloud: pressione Enter para confirmar o ID correto do projeto na nuvem.
• Inserir região do Google Cloud: pressione Enter para usar o padrão us-central1.

3. Inicie o servidor da Web de desenvolvimento

Depois que o agente for criado, inicie o servidor da Web de desenvolvimento executando o seguinte comando:

adk web

Você pode Ctrl + clicar ou Cmd + clicar no link (ou seja, http://localhost:8000) no terminal ou

• Clique no botão Visualização da Web
• Selecione Alterar porta.
• Insira o número da porta (por exemplo, 8000).
• Clique em Alterar e visualizar.

Em seguida, a interface do usuário semelhante a um aplicativo de chat vai aparecer no navegador.

4. Converse com o agente

Converse com seu agente por essa interface. Diga algo como "olá, o que você pode fazer?".

6. Analisar dados de um documento

Nesta seção, você vai fazer upload de um documento para o agente e fazer perguntas sobre o conteúdo dele.

1. Resumir o documento

Siga estas etapas para receber um resumo do documento:

1. Baixe o arquivo sobre a estratégia de saúde do Google.
2. Clique no botão Fazer upload do arquivo na interface do agente e selecione o arquivo que você acabou de baixar.
3. Na interface de chat, peça ao agente para resumir o arquivo: "Faça um resumo deste arquivo".
4. Pressione Enter.

Você vai receber um resumo conciso do conteúdo do documento.

2. Faça perguntas mais detalhadas

Agora, faça perguntas mais detalhadas para se aprofundar no documento:

• Quais são as principais doenças que o Google está segmentando com as iniciativas de IA e dados?
• Como o Google planeja melhorar a interoperabilidade de dados de saúde e eliminar silos de dados?
• Como o Google Cloud está sendo usado para apoiar empresas e pesquisadores da área da saúde?
• Quais novas áreas de doenças o Google pode explorar em seguida (por exemplo, DPOC, câncer, saúde mental)?

3. Faça perguntas complementares

Você também pode fazer perguntas complementares, como descobrir o número de referência da página para investigar mais:

• Onde você viu informações sobre diabetes?
• Me direcione às páginas relevantes sobre doenças.
• Onde estão os gráficos interessantes que devo analisar?

Desafio: encontre um documento seu que você quer que o agente analise e faça upload dele. Faça perguntas ao agente sobre o conteúdo dele.

7. Combinar insights de documentos com pesquisa na Web em tempo real

O agente agora é especialista no documento, mas um analista eficiente também precisa de acesso a informações externas e atuais. Vamos dar ao nosso agente a capacidade de pesquisar na Web.

1. No terminal do Cloud Shell, pressione Ctrl+C para interromper o servidor da Web.
2. Abra o arquivo data_analyst_agent/agent.py no editor do Cloud Shell executando este comando:

cloudshell edit data_analyst_agent/agent.py

3. Modifique o arquivo para importar e adicionar a ferramenta google_search:

from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search

root_agent = Agent(
    model='gemini-2.5-flash',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction="""
        First, check the uploaded files for an answer. 
        If the information is not in the files, use your tools to search the web. 
        Answer user questions to the best of your ability.
    """,
    tools=[
        google_search
    ]
)

OBSERVAÇÃO:a instrução também foi atualizada para orientar o agente sobre quando usar a ferramenta de pesquisa do Google.

4. Salve o arquivo e reinicie o servidor da Web no terminal digitando adk web
5. Na interface do agente, faça o novo upload do arquivo GoogleHealthStrategy.pdf.
6. Agora, faça uma pergunta que exija o contexto do documento e informações externas:

The document discusses Google's strategy in healthcare. What are three other major tech companies that are also investing heavily in healthcare AI, and what are their primary focus areas?

O agente vai sintetizar informações do documento e de uma pesquisa ativa do Google para oferecer uma resposta abrangente. Você pode fazer algumas perguntas:

• O documento menciona o uso de IA para retinopatia diabética. Quais são algumas das tecnologias mais recentes aprovadas pelo FDA nessa área que foram anunciadas no último ano?
• O arquivo menciona parcerias. Você pode encontrar artigos de notícias ou comunicados de imprensa recentes sobre as últimas colaborações do Google no setor de saúde?

Desafio: tente fazer perguntas semelhantes a um documento seu. Algo que usa um documento local e os resultados da Internet.

8. Analisar dados de saúde com o BigQuery

Fazer upload de documentos individuais não é escalonável. Em um cenário real, os dados residem em sistemas corporativos como o Google Cloud BigQuery.

Atualmente, os desenvolvedores que criam aplicativos com agentes precisam criar e manter as próprias ferramentas personalizadas. Esse processo manual é lento, arriscado e cria uma sobrecarga significativa. Isso força os desenvolvedores a lidar com tudo, desde autenticação até tratamento de erros, em vez de se concentrar na inovação.

O Kit de Desenvolvimento de Agente (ADK) inclui ferramentas próprias para interação com o BigQuery. Para essa análise específica, vamos usar o conjunto de dados de utilização do Medicare disponível publicamente, fornecido pelos Centros de Serviços do Medicare e Medicaid (CMS).

Primeiro, vamos conectar nosso agente a um grande conjunto de dados públicos de saúde.

1. No terminal do Cloud Shell, pressione Ctrl+C para interromper o servidor da Web.
2. Abra o arquivo data_analyst_agent/agent.py no Editor do Cloud Shell executando este comando no terminal:

cloudshell edit data_analyst_agent/agent.py

3. Substitua todo o conteúdo do arquivo pelo código a seguir para configurar o BigQueryToolset avançado:

import google.auth
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.bigquery import (
    BigQueryToolset,
    BigQueryCredentialsConfig
)
from google.adk.tools.bigquery.config import (
    BigQueryToolConfig,
    WriteMode
)

# Automatically get credentials from the gcloud environment
application_default_credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
    credentials=application_default_credentials
)

# Configure the BigQuery tool
tool_config = BigQueryToolConfig(
    write_mode=WriteMode.ALLOWED,
    application_name='data_analyst_agent'
)

# Create the toolset with the specified configurations
bigquery_toolset = BigQueryToolset(
    credentials_config=credentials_config, bigquery_tool_config=tool_config
)

# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
    model='gemini-2.5-flash',
    name='google_search_agent',
    description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
    instruction='Use google search to answer user questions about real-time, logistical information.',
    tools=[google_search],
)

# Define the final agent with its instructions and tools
root_agent = Agent(
    model="gemini-2.5-flash",
    name="bigquery_agent",
    description=(
        "Agent to answer questions about BigQuery data and execute SQL queries."
    ),
    instruction="""
        You are an expert data analyst agent with access to BigQuery tools.
        When a user asks about a dataset, first use your tools to understand its schema.
        Then, use this knowledge to construct and execute SQL queries to answer the user's questions.
        Always confirm with the user if their question is ambiguous (e.g., for which year?).
    """,
    tools=[
        AgentTool(google_search_agent),
        bigquery_toolset
    ],
)

4. Salve o arquivo e reinicie o servidor da Web no terminal digitando adk web
5. Agora, você pode pedir ao seu agente para analisar o conjunto de dados público do Medicare. Comece analisando os dados:

Look into the cms_medicare dataset in the bigquery-public-data project. What can you tell me about it?

O agente vai usar as ferramentas dele para inspecionar o conjunto de dados e fornecer uma lista de tabelas disponíveis. A partir daí, você pode detalhar com perguntas analíticas específicas. O agente pode fazer perguntas para esclarecer a situação e garantir que as consultas sejam precisas.

Para algumas perguntas, você precisará fornecer o ID do projeto ao agente para que ele possa usar esse ID e criar uma consulta. Exemplo:

Confira alguns exemplos de comandos analíticos que você pode testar:

• Usando a tabela inpatient_charges_2015, quais são os cinco principais procedimentos (definições de DRG) pelo número total de altas?
• Qual é o pagamento total médio para ‘SUBSTITUIÇÃO DE ARTICULAÇÃO PRINCIPAL' na Califórnia (CA)?
• Qual estado tem a maior média de cobranças cobertas para esse mesmo procedimento?

Isso conclui este codelab. Você mal começou a descobrir o que pode alcançar com agentes de dados que usam sistemas de dados empresariais. Faça ao agente as perguntas que tiver sobre o conjunto de dados cms_medicare.

Desafio:encontre outro conjunto de dados público no BigQuery e use seu agente para explorar. Você também pode criar seu próprio conjunto de dados com seus dados e analisá-los de forma particular.

9. Limpar (opcional)

Observação: se você pretende continuar com a série, NÃO PRECISA fazer esta etapa. Se você estiver participando deste codelab presencialmente com um instrutor, ele vai fornecer mais instruções sobre o que fazer.

Para evitar cobranças futuras, exclua os recursos usados neste codelab.

1. Interromper o agente

No terminal do Cloud Shell, pressione Ctrl+C para interromper o processo adk web.

2. Excluir arquivos do projeto

Para remover o código do agente do ambiente do Cloud Shell, execute o seguinte no terminal:

cd ~ && rm -rf ai-agents-adk

3. Desativar APIs

Para desativar as APIs que você ativou antes, execute o seguinte no terminal:

gcloud services disable \
 aiplatform.googleapis.com \
 bigquery.googleapis.com

4. Encerrar o projeto

Se você quiser excluir todo o projeto do Google Cloud, siga o guia de encerramento de projetos.

10. Conclusão

Parabéns! Você criou um agente de analista de dados usando o framework do Kit de Desenvolvimento de Agente (ADK). Ele pode analisar dados de várias fontes, gerar insights e ajudar a automatizar partes do fluxo de trabalho de análise de dados.

Para continuar sua jornada de aprendizado, explore estes recursos:

• Leia a postagem oficial do blog: Anúncio do conjunto de ferramentas do BigQuery para agentes de IA
• Confira a documentação: acesse a documentação oficial do Kit de Desenvolvimento de Agente (ADK) para conhecer novos recursos e guias avançados.
• Procure o código: confira o repositório do ADK no GitHub.
• Descubra mais dados: confira o catálogo de conjuntos de dados públicos do Google Cloud.