Avalie agentes com o cliente de IA gen no SDK do Vertex AI

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Pode usar o serviço de avaliação de IA gen para avaliar a capacidade do agente de concluir tarefas e alcançar objetivos para um determinado exemplo de utilização.

Esta página mostra-lhe como criar e implementar um agente básico e usar o serviço de avaliação de IA gen para avaliar o agente:

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

• Implemente um agente: implemente o agente no tempo de execução do Vertex AI Agent Engine.

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

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

• Veja os resultados da avaliação: veja os resultados da avaliação através da execução da avaliação.

Para ver um exemplo de como criar uma avaliação de um agente de IA gen para um agente implementado, execute o bloco de notas "Criar e implementar um agente e executar uma avaliação de um agente de IA gen" num 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 Vertex AI para Python:

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

3. Configure as suas credenciais. Se estiver a executar este tutorial no Colaboratory, execute o seguinte:

   from google.colab import auth
   auth.authenticate_user()
   

   Para outros ambientes, consulte o artigo Autenticação no Vertex AI.

4. Inicialize o cliente de IA gen no SDK 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 o seguinte:

   • BUCKET_NAME: nome do contentor do Cloud Storage. Consulte o artigo Crie um contentor para saber mais sobre a criação de contentores.

   • PROJECT_ID: o ID do projeto.

   • LOCATION: a região selecionada.

Desenvolva um agente

Desenvolva um agente do Agent Development Kit (ADK) definindo o modelo, a instrução e o conjunto de ferramentas. Para mais informações sobre o desenvolvimento de um agente, consulte o artigo Desenvolva um agente do 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],
)

Implemente o agente

Implemente o seu agente no tempo de execução do Vertex AI Agent Engine. Esta ação pode demorar até 10 minutos. Obtenha o nome do recurso do 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 ver a lista de agentes implementados no Vertex AI Agent Engine, consulte o artigo Faça a gestão dos agentes implementados.

Gere respostas

1. Gere respostas do modelo para o seu conjunto de dados através da API run_inference():

   Prepare o seu conjunto de dados como um Pandas DataFrame. Os comandos devem ser específicos do seu agente. As entradas de sessão são necessárias para os rastreios. Para mais informações, consulte o artigo Sessão: acompanhamento 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 com 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 juntamente com os comandos e as referências originais:

   agent_dataset_with_inference.show()
   

   A imagem seguinte apresenta o conjunto de dados de avaliação com comandos e os respetivos intermediate_events e responses gerados:

   

Execute a avaliação do agente

Execute create_evaluation_run() para avaliar as respostas do agente.

1. Recupere o agent_info através da 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,
   )
   

Veja os resultados da avaliação do agente

Pode ver os resultados da avaliação através do SDK do Vertex AI.

Obtenha a execução da avaliação e visualize os resultados da avaliação chamando .show() para apresentar 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 seguinte apresenta um relatório de avaliação, que mostra métricas de resumo, informações do agente e resultados detalhados para cada par de comandos-respostas. Os resultados detalhados também incluem rastreios que mostram as interações do agente. Para mais informações sobre rastreios, consulte o artigo Rastreie um agente.



O que se segue?

• Desenvolva um agente.
• Implemente um agente.
• Use um agente.
• Saiba mais sobre o serviço de avaliação de IA gen

Experimente os seguintes blocos de notas:

• Avalie um agente LangChain

• Avalie um agente do LangGraph

• Avalie um agente do CrewAI