Desarrollar un agente de AG2

AG2, una bifurcación de la comunidad del AutoGen original, es un framework de código abierto para crear agentes basados en IA. En esta página se muestra cómo desarrollar un agente mediante la plantilla AG2 específica del framework (la clase AG2Agent del SDK de Vertex AI para Python). El agente devuelve el tipo de cambio entre dos monedas en una fecha específica. A continuación, se indican los pasos que debes seguir:

  1. Definir y configurar un elemento ejecutable
  2. Definir y usar una herramienta
  3. (Opcional) Personaliza la orquestación.

Antes de empezar

Para configurar tu entorno, sigue los pasos que se indican en el artículo Configurar el entorno.

Paso 1. Definir y configurar un elemento ejecutable

Define la versión del modelo que quieras usar.

model = "gemini-2.0-flash"

Define el nombre del elemento ejecutable que se va a usar.

runnable_name = "Get Exchange Rate Agent"

(Opcional) Configura el modelo.

from google.cloud.aiplatform.aiplatform import initializer

llm_config = {
    "config_list": [{
        "project_id":       initializer.global_config.project,
        "location":         initializer.global_config.location,
        "model":            "gemini-2.0-flash",
        "api_type":         "google",
    }]
}

Para obtener más información sobre cómo configurar el modelo en AG2, consulte el artículo Análisis detallado de la configuración del modelo.

(Opcional) Configura los ajustes de seguridad del modelo. A continuación, se muestra un ejemplo de cómo puedes configurar los ajustes de seguridad:

from vertexai.generative_models import HarmBlockThreshold, HarmCategory

safety_settings = {
    HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
    HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_ONLY_HIGH,
    HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
    HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
}

for config_item in llm_config["config_list"]:
    config_item["safety_settings"] = safety_settings

Para obtener más información sobre las opciones disponibles para los ajustes de seguridad en Gemini, consulta Configurar atributos de seguridad.

Crea un AG2Agent con las configuraciones del modelo:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model=model,                  # Required.
    runnable_name=runnable_name,  # Required.
    llm_config=llm_config,        # Optional.
)

Si estás en un entorno interactivo (por ejemplo, un terminal o un cuaderno de Colab), puedes ejecutar una consulta como paso de prueba intermedio:

response = agent.query(input="What is the exchange rate from US dollars to SEK today?", max_turns=1)

print(response)

La respuesta es un diccionario de Python similar al siguiente ejemplo:

{'chat_id': None,
 'chat_history': [{'content': 'What is the exchange rate from US dollars to Swedish currency?',
   'role': 'assistant',
   'name': 'user'},
  {'content': 'I do not have access to real-time information, including currency exchange rates. To get the most up-to-date exchange rate from US dollars to Swedish Krona (SEK), I recommend using a reliable online currency converter or checking with your bank. \n',
   'role': 'user',
   'name': 'Exchange Rate Agent'}],
 'summary': 'I do not have access to real-time information, including currency exchange rates. To get the most up-to-date exchange rate from US dollars to Swedish Krona (SEK), I recommend using a reliable online currency converter or checking with your bank. \n',
 'cost': {'usage_including_cached_inference': {'total_cost': 5.2875e-06,
   'gemini-2.0-flash': {'cost': 5.2875e-06,
    'prompt_tokens': 34,
    'completion_tokens': 62,
    'total_tokens': 96}},
  'usage_excluding_cached_inference': {'total_cost': 5.2875e-06,
   'gemini-2.0-flash': {'cost': 5.2875e-06,
    'prompt_tokens': 34,
    'completion_tokens': 62,
    'total_tokens': 96}}},
 'human_input': []}

(Opcional) Personalización avanzada

La plantilla AG2Agent usa api_type=="google" de forma predeterminada, ya que proporciona acceso a todos los modelos básicos disponibles en Google Cloud. Para usar un modelo que no esté disponible a través de api_type=="google", puedes personalizar el parámetro llm_config.

Para ver una lista de los modelos compatibles con AG2 y sus funciones, consulta Proveedores de modelos. El conjunto de valores admitidos para llm_config= es específico de cada modelo de chat, por lo que debe consultar la documentación correspondiente para obtener más información.

Gemini

Instalado de forma predeterminada.

Se usa en la plantilla AG2Agent cuando se omite el argumento llm_config, por ejemplo:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model=model,                # Required.
    runnable_name=runnable_name # Required.
)

Anthropic

Primero, sigue su documentación para configurar una cuenta e instalar el paquete.

A continuación, define un llm_config:

llm_config = {
    "config_list": [{
        "model": "claude-3-5-sonnet-20240620",            # Required.
        "api_key": "ANTHROPIC_API_KEY",  # Required.
        "api_type": "anthropic",                          # Required.
     }]
}

Por último, úsalo en la plantilla AG2Agent con el siguiente código:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model="claude-3-5-sonnet-20240620",             # Required.
    runnable_name=runnable_name,                    # Required.
    llm_config=llm_config,                          # Optional.
)

OpenAI

Puedes usar OpenAI junto con la API ChatCompletions de Gemini.

Primero, define un llm_config:

import google.auth
from google.cloud.aiplatform.aiplatform import initializer

project = initializer.global_config.project
location = initializer.global_config.location
base_url = f"https://{location}-aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{location}/endpoints/openapi"

# Note: the credential lives for 1 hour by default.
# After expiration, it must be refreshed.
creds, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)

llm_config = {
    "config_list": [{
        "model": "google/gemini-2.0-flash",  # Required.
        "api_type": "openai",                    # Required.
        "base_url": base_url,                    # Required.
        "api_key": creds.token,                  # Required.
    }]
}

Por último, úsalo en la plantilla AG2Agent con el siguiente código:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model="google/gemini-2.0-flash",  # Or "meta/llama3-405b-instruct-maas".
    runnable_name=runnable_name,          # Required.
    llm_config=llm_config,                # Optional.
)

Paso 2: Definir y usar una herramienta

Una vez que hayas definido tu modelo, el siguiente paso es definir las herramientas que usará para razonar. Una herramienta puede ser una herramienta de AG2 o una función de Python.

Cuando definas una función, es importante que incluyas comentarios que describan de forma completa y clara los parámetros de la función, lo que hace la función y lo que devuelve. El modelo usa esta información para determinar qué función debe usar. También debes probar tu función localmente para confirmar que funciona.

Usa el siguiente código para definir una función que devuelva un tipo de cambio:

def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    import requests
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()

Para probar la función antes de usarla en tu agente, ejecuta lo siguiente:

get_exchange_rate(currency_from="USD", currency_to="SEK")

La respuesta debería ser similar a la siguiente:

{'amount': 1.0, 'base': 'USD', 'date': '2024-02-22', 'rates': {'SEK': 10.3043}}

Para usar la herramienta en la plantilla AG2Agent, añádela a la lista de herramientas del argumento tools=:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model=model,                 # Required.
    runnable_name=runnable_name, # Required.
    tools=[get_exchange_rate],   # Optional.
)

Puedes probar el agente de forma local haciendo consultas de prueba. Ejecuta el siguiente comando para probar el agente de forma local con dólares estadounidenses y coronas suecas:

response = agent.query(input="What is the exchange rate from US dollars to Swedish currency?", max_turns=2)

La respuesta es un diccionario similar al siguiente:

{'chat_id': None,
 'chat_history': [{'content': 'What is the exchange rate from US dollars to Swedish currency?',
   'role': 'assistant',
   'name': 'user'},
  {'content': '',
   'tool_calls': [{'id': '2285',
     'function': {'arguments': '{"currency_from": "USD", "currency_to": "SEK"}',
      'name': 'get_exchange_rate'},
     'type': 'function'}],
   'role': 'assistant'},
  {'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}",
   'tool_responses': [{'tool_call_id': '2285',
     'role': 'tool',
     'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}"}],
   'role': 'tool',
   'name': 'user'},
  {'content': 'The current exchange rate is 1 USD to 10.6509 SEK. \n',
   'role': 'user',
   'name': 'Get Exchange Rate Agent'},
  {'content': 'What is the exchange rate from US dollars to Swedish currency?',
   'role': 'assistant',
   'name': 'user'},
  {'content': '',
   'tool_calls': [{'id': '4270',
     'function': {'arguments': '{"currency_from": "USD", "currency_to": "SEK"}',
      'name': 'get_exchange_rate'},
     'type': 'function'}],
   'role': 'assistant'},
  {'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}",
   'tool_responses': [{'tool_call_id': '4270',
     'role': 'tool',
     'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}"}],
   'role': 'tool',
   'name': 'user'},
  {'content': 'The current exchange rate is 1 USD to 10.6509 SEK. \n',
   'role': 'user',
   'name': 'Get Exchange Rate Agent'}],
 'summary': 'The current exchange rate is 1 USD to 10.6509 SEK. \n',
 'cost': {'usage_including_cached_inference': {'total_cost': 0.0002790625,
   'gemini-2.0-flash': {'cost': 0.0002790625,
    'prompt_tokens': 757,
    'completion_tokens': 34,
    'total_tokens': 791}},
  'usage_excluding_cached_inference': {'total_cost': 0.0002790625,
   'gemini-2.0-flash': {'cost': 0.0002790625,
    'prompt_tokens': 757,
    'completion_tokens': 34,
    'total_tokens': 791}}},
 'human_input': []}

Paso 3: Personalizar la orquestación

Todos los agentes de AG2 implementan la interfaz ConversableAgent, que proporciona esquemas de entrada y salida para la orquestación. La AG2Agent necesita que se cree un runnable para poder responder a las consultas. De forma predeterminada, AG2Agent creará un ejecutable vinculando el modelo con las herramientas.

Puede personalizar la orquestación si quiere: (i) implementar un agente asistente que resuelva una tarea con un modelo, (ii) implementar un agente proxy de usuario que pueda ejecutar código y enviar comentarios a los demás agentes, (iii) implementar un agente de razonamiento que resuelva una tarea con un modelo y un razonamiento de árbol de pensamiento. Para ello, debes anular el ejecutable predeterminado al crear el AG2Agent especificando el argumento runnable_builder= con una función de Python que tenga la siguiente firma:


def runnable_builder(
    **runnable_kwargs,
):

De esta forma, se ofrecen diferentes opciones para personalizar la lógica de la orquestación.

Agente asistente

En el caso más sencillo, para crear un agente asistente sin orquestación, puedes anular runnable_builder por AG2Agent.

from vertexai import agent_engines

def runnable_builder(**kwargs):
    from autogen import agentchat

    return agentchat.AssistantAgent(**kwargs)

agent = agent_engines.AG2Agent(
    model=model,
    runnable_name=runnable_name,
    runnable_builder=runnable_builder,
)

User Proxy Agent

En el caso más sencillo, para crear un agente proxy de usuario sin orquestación, puedes anular runnable_builder para AG2Agent.

from vertexai import agent_engines

def runnable_builder(**kwargs):
    from autogen import agentchat

    return agentchat.UserProxyAgent(**kwargs)

agent = agent_engines.AG2Agent(
    model=model,
    runnable_name=runnable_name,
    runnable_builder=runnable_builder,
)

Agente de razonamiento

En el caso más sencillo, para crear un agente de razonamiento sin orquestación, puedes anular runnable_builder por AG2Agent.

from vertexai import agent_engines

def runnable_builder(**kwargs):
    from autogen import agentchat

    return agentchat.ReasoningAgent(**kwargs)

agent = agent_engines.AG2Agent(
    model=model,
    runnable_name=runnable_name,
    runnable_builder=runnable_builder,
)

Siguientes pasos