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

Você pode usar 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 avaliar o agente:

Antes de começar

  1. Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

    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.

    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.

    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 o agente

Implante seu 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 de modelo para seu conjunto de dados usando run_inference():

    Prepare o conjunto de dados como um DataFrame do Pandas. Os comandos precisam ser específicos para o agente. As entradas de sessão são necessárias para traces. 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 de 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 os 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:

    Resultados da avaliação do agente

Executar a avaliação do agente

Executar 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 adaptáveis específicas do agente com base em rubricas adaptáveis com base em rubricas métricas (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 mostra métricas de resumo, informações do agente e resultados detalhados para cada par de comando-resposta. Os resultados detalhados também incluem traces que mostram as interações do agente. Para mais informações sobre traces, consulte Rastrear um agente.

Resultados da avaliação do agente

A seguir

Teste os seguintes notebooks: