Avaliar agentes usando o cliente de IA generativa no SDK da Vertex AI

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Use o serviço de avaliação de IA generativa para avaliar a capacidade do agente de concluir tarefas e metas para um determinado caso de uso.

Nesta página, mostramos como criar e implantar um agente básico e usar o serviço de avaliação de IA generativa para avaliá-lo:

• Desenvolver um agente: defina um agente com funções básicas de ferramentas.

• Implantar um agente: implante o agente no ambiente de execução do Vertex AI Agent Engine.

• Executar a inferência do agente: defina um conjunto de dados de avaliação e execute a inferência do agente para gerar respostas.

• Criar uma execução de avaliação: crie uma execução de avaliação para realizar a avaliação.

• Conferir os resultados da avaliação: confira os resultados da avaliação na execução dela.

Para conferir um exemplo de como criar uma avaliação de agente de IA generativa para um agente implantado, execute o notebook "Criar e implantar um agente e executar uma avaliação de agente de IA generativa" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Vertex AI Workbench | Ver no GitHub

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

2. Instale o SDK da Vertex AI para Python:

   %pip install google-cloud-aiplatform[adk,agent_engines]
   %pip install --upgrade --force-reinstall -q google-cloud-aiplatform[evaluation]
   

3. Configure suas credenciais. Se você estiver executando este tutorial no Colaboratory, faça o seguinte:

   from google.colab import auth
   auth.authenticate_user()
   

   Para outros ambientes, consulte Autenticar na Vertex AI.

4. Inicialize o cliente da IA generativa no SDK da Vertex AI:

   import vertexai
   from vertexai import Client
   from google.genai import types as genai_types
   
   GCS_DEST = "gs://BUCKET_NAME/output-path"
   vertexai.init(
       project=PROJECT_ID,
       location=LOCATION,
   )
   
   client = Client(
       project=PROJECT_ID,
       location=LOCATION,
       http_options=genai_types.HttpOptions(api_version="v1beta1"),
     )
   

   Substitua:

   • BUCKET_NAME: nome do bucket do Cloud Storage. Consulte Criar um bucket para saber mais sobre como criar buckets.

   • PROJECT_ID: o ID do projeto.

   • LOCATION: a região selecionada.

Desenvolver um agente

Desenvolva um agente do Kit de Desenvolvimento de Agente (ADK) definindo o modelo, a instrução e o conjunto de ferramentas. Para mais informações sobre como desenvolver um agente, consulte Desenvolver um agente do Kit de Desenvolvimento de Agente.

from google.adk import Agent

# Define Agent Tools
def search_products(query: str):
    """Searches for products based on a query."""
    # Mock response for demonstration
    if "headphones" in query.lower():
        return {"products": [{"name": "Wireless Headphones", "id": "B08H8H8H8H"}]}
    else:
        return {"products": []}

def get_product_details(product_id: str):
    """Gets the details for a given product ID."""
    if product_id == "B08H8H8H8H":
        return {"details": "Noise-cancelling, 20-hour battery life."}
    else:
        return {"error": "Product not found."}

def add_to_cart(product_id: str, quantity: int):
    """Adds a specified quantity of a product to the cart."""
    return {"status": f"Added {quantity} of {product_id} to cart."}

# Define Agent
my_agent = Agent(
    model="gemini-2.5-flash",
    name='ecommerce_agent',
    instruction='You are an ecommerce expert',
    tools=[search_products, get_product_details, add_to_cart],
)

Implantar agente

Implante o agente no ambiente de execução do Vertex AI Agent Engine. Isso pode levar até 10 minutos. Recupere o nome do recurso do agente implantado.

def deploy_adk_agent(root_agent):
  """Deploy agent to agent engine.
  Args:
    root_agent: The ADK agent to deploy.
  """
  app = vertexai.agent_engines.AdkApp(
      agent=root_agent,
  )
  remote_app = client.agent_engines.create(
      agent=app,
      config = {
          "staging_bucket": gs://BUCKET_NAME,
          "requirements": ['google-cloud-aiplatform[adk,agent_engines]'],
          "env_vars": {"GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY": "true"}
      }
  )
  return remote_app

agent_engine = deploy_adk_agent(my_agent)
agent_engine_resource_name = agent_engine.api_resource.name

Para conferir a lista de agentes implantados no Vertex AI Agent Engine, consulte Gerenciar agentes implantados.

Gerar respostas

1. Gere respostas do modelo para seu conjunto de dados usando run_inference():

   Prepare seu conjunto de dados como um DataFrame do Pandas. Os comandos precisam ser específicos para seu agente. As entradas de sessão são obrigatórias para rastreamentos. Para mais informações, consulte Sessão: rastreamento de conversas individuais.

   import pandas as pd
   from vertexai import types
   
   session_inputs = types.evals.SessionInput(
       user_id="user_123",
       state={},
   )
   agent_prompts = [
       "Search for 'noise-cancelling headphones'.",
       "Show me the details for product 'B08H8H8H8H'.",
       "Add one pair of 'B08H8H8H8H' to my shopping cart.",
       "Find 'wireless earbuds' and then add the first result to my cart.",
       "I need a new laptop for work, can you find one with at least 16GB of RAM?",
   ]
   agent_dataset = pd.DataFrame({
       "prompt": agent_prompts,
       "session_inputs": [session_inputs] * len(agent_prompts),
   })
   

2. Gere respostas do modelo usando run_inference():

   agent_dataset_with_inference = client.evals.run_inference(
       agent=agent_engine_resource_name,
       src=agent_dataset,
   )
   

3. Visualize os resultados da inferência chamando .show() no objeto EvaluationDataset para inspecionar as saídas do modelo junto com seus comandos e referências originais:

   agent_dataset_with_inference.show()
   

   A imagem a seguir mostra o conjunto de dados de avaliação com comandos e os intermediate_events e responses gerados correspondentes:

   

Executar a avaliação do agente

Execute create_evaluation_run() para avaliar as respostas do agente.

1. Recupere o agent_info usando a função auxiliar integrada:

   agent_info = types.evals.AgentInfo.load_from_agent(
       my_agent,
       agent_engine_resource_name
   )
   

2. Avalie as respostas do modelo usando métricas adaptativas baseadas em rubricas específicas do agente (FINAL_RESPONSE_QUALITY, TOOL_USE_QUALITY e HALLUCINATION):

   evaluation_run = client.evals.create_evaluation_run(
       dataset=agent_dataset_with_inference,
       agent_info=agent_info,
       metrics=[
           types.RubricMetric.FINAL_RESPONSE_QUALITY,
           types.RubricMetric.TOOL_USE_QUALITY,
           types.RubricMetric.HALLUCINATION,
           types.RubricMetric.SAFETY,
       ],
       dest=GCS_DEST,
   )
   

Conferir os resultados da avaliação do agente

É possível conferir os resultados da avaliação usando o SDK da Vertex AI.

Recupere a execução da avaliação e visualize os resultados chamando .show() para mostrar métricas de resumo e resultados detalhados:

evaluation_run = client.evals.get_evaluation_run(
    name=evaluation_run.name,
    include_evaluation_items=True
)

evaluation_run.show()

A imagem a seguir mostra um relatório de avaliação, que apresenta métricas de resumo, informações do agente e resultados detalhados para cada par de solicitação-resposta. Os resultados detalhados também incluem rastreamentos que mostram as interações do agente. Para mais informações sobre traces, consulte Rastrear um agente.



A seguir

• Desenvolver um agente.
• Implante um agente.
• Use um agente.
• Saiba mais sobre o serviço de avaliação de IA generativa

Teste os seguintes notebooks:

• Avaliar um agente do LangChain

• Avaliar um agente do LangGraph

• Avaliar um agente do CrewAI