Analisar a execução do agente do ADK com o plug-in de análise de agentes do BigQuery

1. Introdução

Neste codelab, você vai criar um sistema multiagente usando o Kit de desenvolvimento de agentes (ADK) e ativar a capacidade de observação do agente com o plug-in de análise de agentes do BigQuery.Você vai fazer uma série de perguntas ao agente e usar o BigQuery para analisar rastreamentos de conversas e o uso de ferramentas do agente.

O que você aprenderá

• Criar um assistente de varejo multiagente usando o ADK
• Inicialize o plug-in de análise do agente do BigQuery para capturar e armazenar dados de rastreamento sobre a execução desse agente no BigQuery.
• Analisar os dados de registros do agente no BigQuery

O que é necessário

• Um navegador da Web, como o Chrome
• Um projeto do Google Cloud com o faturamento ativado ou
• Uma conta do Gmail. Na próxima seção, vamos mostrar como resgatar um crédito sem custo financeiro de US $5 para este codelab e configurar um novo projeto.

Este codelab é destinado a desenvolvedores de todos os níveis, incluindo iniciantes. Você vai usar a interface de linha de comando no Cloud Shell e o código Python para o desenvolvimento do ADK. Você não precisa ser um especialista em Python, mas um entendimento básico de como ler código vai ajudar a entender os conceitos.

2. Antes de começar

Para créditos do Google Cloud:para ajudar você a começar, resgate seus créditos sem custo financeiro do Google Cloud usando este link. Siga as instruções aqui para ativar o crédito e criar um projeto.

Criar um projeto do Google Cloud

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

Inicie o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud:

2. Depois de se conectar ao Cloud Shell, execute este comando para verificar sua autenticação no Cloud Shell:

gcloud auth list

3. Execute o comando a seguir para confirmar se o projeto está configurado para uso com a gcloud:

gcloud config get project

4. Se o projeto não estiver configurado como esperado, use o seguinte comando para definir o projeto:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Ativar APIs

1. Execute este comando para ativar todas as APIs e serviços necessários:

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

2. Após a execução do comando, você vai ver uma mensagem semelhante à mostrada abaixo:

Operation "operations/..." finished successfully.

3. Instalação e configuração

Volte ao Cloud Shell e verifique se você está no diretório inicial.

Execute o comando a seguir no Cloud Shell para criar um conjunto de dados chamado adk_logs no BigQuery:

bq mk --dataset --location=US adk_logs

Agora, vamos criar um ambiente virtual do Python e instalar os pacotes necessários.

1. Abra uma nova guia de terminal no Cloud Shell e execute este comando para criar e acessar uma pasta chamada adk-agent-observability:

mkdir adk-agent-observability
cd adk-agent-observability

2. Crie um ambiente virtual Python:

python -m venv .venv

3. Ative o ambiente virtual:

source .venv/bin/activate

4. Instale o ADK:

pip install --upgrade google-adk

4. Criar um aplicativo ADK

Agora, vamos criar nosso agente assistente de varejo. Esse agente será projetado para ...

1. Execute o comando de utilitário adk create para criar um novo aplicativo de agente com as pastas e arquivos necessários:

adk create retail_assistant_app

Siga as instruções:

1. Escolha gemini-2.5-flash para o modelo.
2. Escolha Vertex AI para o back-end.
3. Confirme o ID e a região padrão do projeto do Google Cloud.

Confira um exemplo de interação abaixo:

2. Clique no botão "Abrir editor" no Cloud Shell para abrir o editor do Cloud Shell e conferir as pastas e os arquivos recém-criados:

Observe os arquivos gerados:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env

• init.py::marca a pasta como um módulo do Python.
• agent.py::contém a definição inicial do agente.
• .env:talvez seja necessário clicar em "Visualizar > Alternar arquivos ocultos" para ver esse arquivo.

• O arquivo .env contém variáveis de ambiente para seu projeto. Atualize as variáveis que não foram definidas corretamente nos comandos:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

5. Definir o agente

Agora vamos definir um sistema multiagente hierárquico.

1. Agente de tendências em tempo real:usa a Pesquisa Google para encontrar as tendências de moda atuais.
2. Agente de dados de inventário:usa o conjunto de ferramentas do BigQuery para consultar o conjunto de dados público thelook_ecommerce em busca de produtos disponíveis.
3. Agente assistente de varejo (raiz):orquestra o fluxo de trabalho pedindo conselhos ao agente de tendências e produtos correspondentes ao agente de inventário.

Substitua todo o conteúdo de retail_assistant_app/agent.py pelo código abaixo.

import os
import uuid
import asyncio
import google.auth
import dotenv
from google.genai import types
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.adk.tools import AgentTool, google_search
from google.adk.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

dotenv.load_dotenv()

# --- Configuration ---

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
DATASET_ID = "adk_logs"
TABLE_ID = "retail_assistant_agent_logs"
APP_NAME = "retail_assistant_agent"
USER_ID = "test_user"

# --- Toolsets ---

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

# --- Agents ---

# 1. Trend Spotter
real_time_agent = Agent(
   name="real_time_agent",
   model="gemini-2.5-flash",
    description="Researches external factors like weather, local events, and current fashion trends.",
   instruction="""
       You are a real-time research agent.
       Use Google Search to find real-time information relevant to the user's request,
       such as the current weather in their location or trending styles.
   """,
   tools=[google_search]
)

# 2. Inventory Manager
inventory_data_agent = Agent(
   name="inventory_data_agent",
   model="gemini-2.5-flash",
   description="Oversees product inventory in the BigQuery `thelook_ecommerce` dataset to find available items and prices.",
   instruction=f"""
   You manage the inventory. You have access to the `bigquery-public-data.thelook_ecommerce` dataset via the BigQuery toolset.
   Run all BigQuery queries the project id of: '{PROJECT_ID}'
  
   Your workflow:
   1. Look at the products table.
   2. Find items that match the requirements, factor in the results from the trend_setter agent if there are any.
   3. Return with a user friendly response, including the list of specific products and prices.
   """,
   tools=[bigquery_toolset]
)

# 3. Root Orchestrator
root_agent = Agent(
   name="retail_assistant",
   model="gemini-2.5-flash",   
   description="The primary orchestrator, responsible for handling user input, delegating to sub-agents, and synthesizing the final product recommendation.",
   instruction="""
   You are a Retail Assistant.   
   You can ask the 'real_time_agent' agent for any realtime information needed, or style advice, include any information provided by the user.
   You should ask the 'inventory_data_agent' agent to find a maximum of 3 available items matching that style.
   Combine the results into a recommendation.
   """,
   tools=[AgentTool(agent=real_time_agent)],
   sub_agents=[inventory_data_agent]
)

6. Gerar registros com o plug-in BigQuery Agent Analytics

Agora, vamos configurar o plug-in de análise do agente do BigQuery para capturar dados de execução.

Para isso, crie uma instância da classe App. Essa classe serve como o contêiner de tempo de execução do seu agente. Ela gerencia o loop de conversa, processa o estado do usuário e organiza os plug-ins anexados (como nosso registrador de análise do agente).

O código abaixo:

• Inicializa o plug-in de geração de registros:cria o BigQueryAgentAnalyticsPlugin com os detalhes de conexão necessários.
• Integra o plug-in:transmite o plug-in do BigQuery inicializado para o construtor App, garantindo que os eventos de execução do agente sejam capturados e registrados automaticamente.
• Execução do agente de execuções e registros:executa o fluxo de conversa via runner.run_async. Ao mesmo tempo, o plug-in coleta e envia toda a sequência de eventos para o BigQuery antes de fechar os recursos.

Copie e cole este código abaixo das definições de agente no arquivo agent.py:

async def main(prompt: str):
    """Runs a conversation with the BigQuery agent using the ADK Runner."""
    bq_logger_plugin = BigQueryAgentAnalyticsPlugin(
        project_id=PROJECT_ID, dataset_id=DATASET_ID, table_id=TABLE_ID
    )
    app = App(name=APP_NAME, root_agent=root_agent, plugins=[bq_logger_plugin])
    runner = InMemoryRunner(app=app)

    try:
        session_id = f"{USER_ID}_{uuid.uuid4().hex[:8]}"

        my_session = await runner.session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID, session_id=session_id
        )

        async for event in runner.run_async(
            user_id=USER_ID,
            new_message=types.Content(
                role="user", parts=[types.Part.from_text(text=prompt)]
            ),
            session_id=my_session.id,
        ):
            if event.content.parts and event.content.parts[0].text:
                print(f"** {event.author}: {event.content.parts[0].text}")

    except Exception as e:
        print(f"Error in main: {e}")
    finally:
        print("Closing BQ Plugin...")
        await bq_logger_plugin.close()
        print("BQ Plugin closed.")

if __name__ == "__main__":
   prompts = [
       "what outfits do you have available that are suitable for the weather in london this week?",      
       "You are such a cool agent! I need a gift idea for my friend who likes yoga.",       
       "I'd like to complain - the products sold here are not very good quality!"
   ]
   for prompt, prompt in enumerate(prompts):
       asyncio.run(main(prompt))

Com a instrumentação no lugar, é hora de ver o agente em ação. Execute o script para acionar o fluxo de trabalho de conversa.

python retail_assistant_app/agent.py

Você vai notar que o assistente de varejo está orquestrando o fluxo de trabalho:

1. Ele pede ao agente de tendências em tempo real (real_time_agent) para identificar o clima em Londres e pesquisar tendências de moda adequadas.
2. Em seguida, ele delega ao Agente de dados de inventário (inventory_data_agent) para consultar o conjunto de dados do BigQuery thelook_ecommerce em busca de produtos específicos que correspondam a essas tendências.
3. Por fim, o orquestrador raiz sintetiza os resultados em uma recomendação final.

Enquanto isso, o plug-in transmite o rastreamento de execução do agente para o BigQuery.

7. Analisar registros do agente

Uso de ferramentas

Agora podemos ver o que nosso agente estava fazendo nos bastidores. Os dados foram transmitidos para o BigQuery e estão prontos para análise:

1. No console do Google Cloud, pesquise BigQuery.
2. No painel Explorador, localize seu projeto.
3. Expanda o conjunto de dados adk_logs.
4. Abra a tabela retail_assitant_agent_logs e clique em Consulta.

Para ver quais chamadas de função seu agente fez e capturar erros de função, execute a seguinte consulta no editor do BigQuery:

SELECT
   -- Extract text between "Tool Name: " and the next comma (or end of line)
   REGEXP_EXTRACT(content, r'Tool Name: ([^,]+)') AS tool_name,
   -- Count every time a tool finished (successfully or with an error)
   COUNT(*) AS total_finished_runs,
   -- Count it as a failure if it's an explicit system error OR contains "error" in the text
   COUNTIF(event_type = 'TOOL_ERROR' OR REGEXP_CONTAINS(content, r'(?i)\berror\b')) AS failure_count
FROM
   `.adk_logs.retail_assistant_agent_logs`
WHERE
   event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
   1

Clique em "Visualização" para ver isso como um gráfico:

Uso de tokens

Para inferir o custo dos seus agentes, agregue os tokens de solicitação e de candidato consumidos por cada agente distinto:

SELECT
     t.agent,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'prompt:\s*(\d+)') AS INT64)) AS prompt_tokens,
     SUM(CAST(REGEXP_EXTRACT(t.content, r'candidates:\s*(\d+)') AS INT64)) AS candidate_tokens
   FROM
     `adk_logs.retail_assistant_agent_logs` AS t
   WHERE
     t.event_type = 'LLM_RESPONSE'
     AND t.content LIKE '%Token Usage: %'
   GROUP BY 1

Clique em "Visualização" para ver isso como um gráfico:

8. [Bônus] Analisar o sentimento do usuário

Agora vamos analisar o sentimento da entrada do usuário fornecida ao agente.

1. Crie uma conexão de recursos do Cloud para permitir que o BigQuery interaja com os serviços da Vertex AI:

bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

Você vai receber uma resposta como esta:

A conexão 517325854360.us.test_connection foi criada

2. Crie uma conexão de recursos da nuvem:

export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)

3. Execute este comando para validar se a conta de serviço foi criada com sucesso:

echo $SERVICE_ACCOUNT_EMAIL

Sua conta de serviço vai aparecer:

4. Conceda à conta de serviço de conexão de recursos as permissões no nível do projeto necessárias para interagir com a Vertex AI:

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/bigquery.connectionUser' \
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/aiplatform.user'

Aguarde alguns minutos e execute a função AI.SCORE do BigQuery para analisar o sentimento do usuário:

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', content,
   'Use a scale from 1 to 5.'),
 connection_id => 'us.test_connection') AS user_sentiment
FROM
 `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type = 'USER_MESSAGE_RECEIVED'
ORDER BY
 user_sentiment DESC;

A função AI.SCORE atribui um valor de sentimento entre 1 e 5 para cada entrada do usuário. Você vai ver resultados como este:

9. Limpeza

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este workshop.

Exclua o conjunto de dados de registros criado pelo script:

bq rm -r -f -d $PROJECT_ID:adk_logs

Para remover o diretório bigquery-adk-codelab e o conteúdo dele:

cd .. 
rm -rf adk-agent-observability

10. Parabéns

Parabéns! Você criou um sistema multiagente com o Kit de Desenvolvimento de Agente (ADK) e integrou o plug-in de análise de agente do BigQuery para rastrear e auditar o comportamento do seu agente.

Documentos de referência

• Documentação do plug-in de geração de registros do BigQuery do ADK
• Formulário de interesse do plug-in de geração de registros do BigQuery