Evalúa agentes con el cliente de GenAI en el SDK de Vertex AI

Versión preliminar

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes usar el servicio de evaluación de IA generativa para evaluar la capacidad del agente de completar tareas y objetivos para un caso de uso determinado.

En esta página, se muestra cómo crear e implementar un agente básico y usar el servicio de evaluación de IA generativa para evaluar el agente:

• Desarrolla un agente: Define un agente con funciones básicas de herramientas.

• Implementa un agente: Implementa el agente en el entorno de ejecución de Vertex AI Agent Engine.

• Ejecuta la inferencia del agente: Define un conjunto de datos de evaluación y ejecuta la inferencia del agente para generar respuestas.

• Create evaluation run: Crea una ejecución de evaluación para realizar la evaluación.

• Ver los resultados de la evaluación: Consulta los resultados de la evaluación a través de la ejecución de la evaluación.

Para ver un ejemplo de cómo crear una evaluación de agentes de IA generativa para un agente implementado, ejecuta el notebook “Crea e implementa un agente y ejecuta una evaluación de agentes de IA generativa” en uno de los siguientes entornos:

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

Antes de comenzar

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. Instala el SDK de Vertex AI para Python:

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

3. Configura tus credenciales. Si ejecutas este instructivo en Colaboratory, ejecuta lo siguiente:

   from google.colab import auth
   auth.authenticate_user()
   

   Para otros entornos, consulta Autentícate en Vertex AI.

4. Inicializa el cliente de IA generativa en el SDK de 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"),
     )
   

   Reemplaza lo siguiente:

   • BUCKET_NAME: Es el nombre del bucket de Cloud Storage. Consulta Crea un bucket para obtener más información sobre cómo crear buckets.

   • PROJECT_ID: ID del proyecto

   • LOCATION: La región que seleccionaste.

Desarrolla un agente

Desarrolla un agente del Kit de desarrollo de agentes (ADK) definiendo el modelo, la instrucción y el conjunto de herramientas. Para obtener más información sobre cómo desarrollar un agente, consulta Cómo desarrollar un agente del Kit de desarrollo de agentes.

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],
)

Implementar agente

Implementa tu agente en el entorno de ejecución de Agent Engine de Vertex AI. Este proceso puede tardar hasta 10 minutos. Recupera el nombre del recurso del agente implementado.

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 obtener la lista de agentes implementados en Vertex AI Agent Engine, consulta Administra agentes implementados.

Genera respuestas

1. Genera respuestas del modelo para tu conjunto de datos con run_inference():

   Prepara tu conjunto de datos como un DataFrame de Pandas. Las instrucciones deben ser específicas para tu agente. Las entradas de sesión son obligatorias para los registros. Para obtener más información, consulta Sesión: Seguimiento de conversaciones individuales.

   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. Genera respuestas del modelo con run_inference():

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

3. Visualiza los resultados de la inferencia llamando a .show() en el objeto EvaluationDataset para inspeccionar los resultados del modelo junto con tus instrucciones y referencias originales:

   agent_dataset_with_inference.show()
   

   En la siguiente imagen, se muestra el conjunto de datos de evaluación con instrucciones y sus correspondientes intermediate_events y responses generados:

   

Ejecuta la evaluación del agente

Ejecuta create_evaluation_run() para evaluar las respuestas del agente.

1. Recupera el agent_info con la función de ayuda integrada:

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

2. Evalúa las respuestas del modelo con métricas adaptables basadas en rúbricas específicas del agente (FINAL_RESPONSE_QUALITY, TOOL_USE_QUALITY y 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,
   )
   

Cómo ver los resultados de la evaluación del agente

Puedes ver los resultados de la evaluación con el SDK de Vertex AI.

Recupera la ejecución de la evaluación y visualiza los resultados de la evaluación llamando a .show() para mostrar las métricas de resumen y los resultados detallados:

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

evaluation_run.show()

En la siguiente imagen, se muestra un informe de evaluación, que incluye métricas de resumen, información del agente y resultados detallados para cada par de instrucciones y respuestas. Los resultados detallados también incluyen registros que muestran las interacciones del agente. Para obtener más información sobre los seguimientos, consulta Cómo hacer un seguimiento de un agente.



¿Qué sigue?

• Desarrolla un agente.
• Implementa un agente.
• Usa un agente.
• Más información sobre el servicio de evaluación de IA generativa

Prueba los siguientes notebooks:

• Evalúa un agente de LangChain

• Evalúa un agente de LangGraph

• Evalúa un agente de CrewAI