Evaluar agentes con el cliente de IA generativa en el SDK de Vertex AI

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Puedes usar el servicio de evaluación de IA generativa para evaluar la capacidad del agente de completar tareas y objetivos en un caso práctico concreto.

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

• Desarrollar un agente: define un agente con funciones de herramientas básicas.

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

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

• Crear ejecución de evaluación: crea una ejecución de evaluación para llevar a cabo 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 agente de IA generativa para un agente implementado, ejecuta el cuaderno "Create & Deploy Agent and Run Gen AI Agent Evaluation" (Crear e implementar un agente y ejecutar una evaluación de agente 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 empezar

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 estás siguiendo este tutorial en Colaboratory, ejecuta lo siguiente:

   from google.colab import auth
   auth.authenticate_user()
   

   En otros entornos, consulta Autenticarse 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"),
     )
   

   Haz los cambios siguientes:

   • BUCKET_NAME: nombre del segmento de Cloud Storage. Consulta Crear un segmento para obtener más información sobre cómo crear segmentos.

   • PROJECT_ID: tu ID de proyecto.

   • LOCATION: la región que has seleccionado.

Desarrollar un agente

Desarrolla un agente de Agent Development Kit (ADK) definiendo el modelo, las instrucciones y el conjunto de herramientas. Para obtener más información sobre cómo desarrollar un agente, consulta Desarrollar un agente de Agent Development Kit.

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

Desplegar agente

Despliega tu agente en el entorno de ejecución de Vertex AI Agent Engine. Este proceso puede tardar hasta 10 minutos. Obtén 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 desplegados en Vertex AI Agent Engine, consulta Gestionar agentes desplegados.

Generar respuestas

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

   Prepara tu conjunto de datos como Pandas DataFrame. Las peticiones deben ser específicas para tu agente. Se necesitan entradas de sesión para las trazas. 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. Generar 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 peticiones y referencias originales:

   agent_dataset_with_inference.show()
   

   En la siguiente imagen se muestra el conjunto de datos de evaluación con las peticiones y los intermediate_events y responses generados correspondientes:

   

Ejecutar la evaluación del agente

Ejecuta create_evaluation_run() para evaluar las respuestas del agente.

1. Recupera el agent_info con la función auxiliar 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 adaptativas 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,
   )
   

Ver los resultados de la evaluación del agente

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

Recupere la ejecución de la evaluación y visualice 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 de cada par de peticiones y respuestas. Los resultados detallados también incluyen trazas que muestran las interacciones del agente. Para obtener más información sobre los rastreos, consulta Rastrear un agente.



Siguientes pasos

• Desarrolla un agente.
• Desplegar un agente.
• Usar un agente.
• Consulta más información sobre el servicio de evaluación de la IA generativa.

Prueba los siguientes cuadernos:

• Evaluar un agente de LangChain

• Evaluar un agente de LangGraph

• Evaluar un agente de CrewAI