Crea una aplicación de agente

En esta guía, se explican los pasos necesarios para crear una aplicación de agente básica que pueda responder las consultas de los usuarios sobre el clima.

Antes de comenzar

Asegúrate de completar las instrucciones de configuración antes de seguir esta guía.

Crea una aplicación de agente

Para crear una aplicación de agente y un agente raíz, haz lo siguiente:

  1. Abre la consola de CX Agent Studio.
  2. Elige tu proyecto.
  3. Haz clic en Crear agente o Agente nuevo.
  4. Proporciona "app del clima" como nombre del agente.
  5. Haz clic en Crear. Si es la primera aplicación de agente que creaste para el proyecto, la creación puede tardar entre 1 y 2 minutos. Se muestra el generador de agentes y se crea un agente raíz.

Crea la jerarquía de agentes

Esta aplicación de agente usará tres agentes:

  • Agente raíz para saludar al usuario y delegar en otros agentes secundarios
  • Agente del clima para responder preguntas relacionadas con el clima
  • Agente de despedida para completar la conversación

El agente raíz ya está creado, pero debes actualizar la configuración de este agente:

  1. Haz clic en la barra de título del agente raíz.
  2. De manera opcional, puedes cambiar el nombre del agente.
  3. Ingresa la descripción: "Maneja saludos simples y delega en otros agentes".
  4. Haz clic en Guardar y, luego, cierra el panel de configuración.

Para crear el agente del clima, haz lo siguiente:

  1. Haz clic en el botón + en la parte inferior del agente raíz.
  2. Haz clic en Agregar agente secundario nuevo.
  3. Haz clic en la barra de título del agente nuevo.
  4. Cambia el nombre a "Agente del clima".
  5. Ingresa la descripción: "Maneja cualquier pregunta relacionada con el clima del usuario".
  6. Haz clic en Guardar y, luego, cierra el panel de configuración.

De manera similar, crea otro agente secundario del agente raíz llamado "Agente de despedida" con una descripción de "Maneja las despedidas y los adiós de los usuarios".

Captura de pantalla de la jerarquía del agente

Crea una herramienta del clima

Las herramientas se usan para conectar tu agente a sistemas externos o al código intercalado que se le proporciona. Esto permite que tu agente interactúe con otros sistemas para recuperar, actualizar, dar formato o analizar información.

En este paso, crearás una herramienta del clima, que se usa para recuperar información sobre el clima. A los efectos de esta guía, esta herramienta tiene una respuesta simulada para el usuario. En una aplicación del clima real, esta herramienta accedería a un servidor externo para obtener información.

Para crear la herramienta del clima, haz lo siguiente:

  1. Haz clic en el botón de herramientas que se encuentra en el lado derecho del generador de agentes.
  2. Haz clic en + para crear una herramienta nueva para la aplicación de agente.
  3. Haz clic en Código de Python.

  4. Pega el siguiente código:

    def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city.

  Returns:
    dict: A dictionary containing the weather information.
          Includes a 'status' key ('success' or 'error').
          If 'success', includes a 'report' key with weather details.
          If 'error', includes an 'error_message' key.
  """
  city_normalized = city.lower().replace(" ", "")

  mock_weather_db = {
    "newyork": {"status": "success",
      "report": "The weather in New York is sunny and 25°C."},
    "london": {"status": "success",
      "report": "It's cloudy in London and  15°C."},
    "tokyo": {"status": "success",
      "report": "Tokyo is experiencing light rain and 18°C."},
  }
  if city_normalized in mock_weather_db:
    return mock_weather_db[city_normalized]
  else:
    return {"status": "error",
      "error_message": f"No weather information for '{city}'."}

  5. Haz clic en Crear.

Ahora, debes agregar esta herramienta al agente del clima:

  1. Haz clic en el botón + en la barra de título del agente del clima.
  2. Haz clic en Agregar herramienta.
  3. Selecciona la herramienta del clima.

Crea instrucciones del agente

Cada agente tiene un conjunto de instrucciones que definen lo que debe hacer.

Cuando proporciones instrucciones que hagan referencia a un agente, usa la sintaxis {@AGENT: Agent name}. Para hacer referencia a las herramientas, usa {@TOOL: tool_name}.

Para crear instrucciones para cada agente, haz lo siguiente:

  1. Haz clic en el botón + en la barra de título del agente raíz.
  2. Haz clic en Agregar instrucciones.

  3. Ingresa las siguientes instrucciones:

    You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
When greeting the user, describe how you can help them.
When the user asks for the weather, delegate to {@AGENT: Weather agent}.
When the user is ending the conversation,
delegate to {@AGENT: Farewell agent}.
Handle only weather requests, greetings, and farewells.

  4. Haz clic en Crear.

  5. De manera similar, agrega las siguientes instrucciones para el agente del clima:

    You are a helpful weather agent.
When the user asks for the weather in a specific city,
use {@TOOL: get_weather} to find the information.
If the tool returns an error, inform the user politely.
If the tool is successful, present the weather report clearly.

  6. De manera similar, agrega las siguientes instrucciones para el agente de despedida:

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.

Prueba el agente

Tu aplicación de agente ya está lista para las interacciones con el simulador:

  1. En la esquina inferior izquierda de la pantalla de la consola, haz clic en la barra Vista previa del agente para expandir la ventana si aún no está expandida.
  2. Escribe "hola" y, luego, presiona Intro. El agente responde con un saludo genérico.
  3. Escribe "¿cómo está el clima en Nueva York?" y, luego, presiona Intro. El agente responde con información sobre el clima.
  4. Escribe "adiós" y, luego, presiona Intro. El agente concluye la conversación.

Usa variables

Las variables se usan para almacenar y recuperar datos de conversaciones en entorno de ejecución. Esto permite que los agentes recuerden información en los turnos de conversación, lo que lleva a interacciones más contextuales. Para este agente, crearás una variable que capture el nombre del usuario.

Para crear la variable, haz lo siguiente:

  1. Haz clic en el botón de variables que se encuentra en el lado derecho del generador de agentes.
  2. Haz clic en Crear una variable o +.
  3. Escribe "nombre de usuario" como nombre de la variable.
  4. Deja el tipo como Texto.
  5. Haz clic en Crear.

Ahora que definiste la variable, debes definir una herramienta que permita que el agente la actualice:

  1. Haz clic en el botón de herramientas que se encuentra en el lado derecho del generador de agentes.
  2. Haz clic en + para crear una herramienta nueva para la aplicación de agente.
  3. Haz clic en Código de Python.

  4. Pega el siguiente código:

    from typing import Optional

def update_username(username: str) -> Optional[str]:
  """Updates the current user's name"""
  set_variable("username", username)

  5. Haz clic en Crear.

Agrega esta herramienta al agente raíz:

  1. Haz clic en el botón + en la barra de título del agente raíz.
  2. Haz clic en Agregar herramienta.
  3. Selecciona la herramienta update_username.

Agrega la siguiente oración a las instrucciones del agente raíz, que hace referencia a la variable con la sintaxis {variable_name}:

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

Puedes volver a probar el agente para verificar el uso de la variable:

  1. Haz clic en Iniciar conversación nueva en la barra de título del simulador.
  2. Ingresa "Hola, mi nombre es Frank".
  3. Ingresa "¿Qué tan precisa es tu información?".

Ten en cuenta que el agente ahora responde con tu nombre en cada respuesta. También puedes expandir las secciones Pasos de la conversación del simulador, en las que puedes verificar la ejecución de la herramienta, entre otras cosas.

Controla cómo finalizar la sesión

De forma predeterminada, cada uno de tus agentes está configurado para usar la end_session herramienta del sistema, sin embargo, puedes mejorar la confiabilidad y el control de cómo finalizar la sesión creando instrucciones explícitas.

Para quitar las herramientas end_session de los agentes raíz y del clima, haz clic en la x junto a la herramienta de cada agente. Esto garantiza que solo tu agente de despedida finalizará la sesión.

Agrega lo siguiente a las instrucciones de tu agente de despedida:

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

Usa una devolución de llamada para aplicar un mensaje estático al final de la sesión

Las devoluciones de llamada proporcionan un mecanismo para conectarse al proceso de ejecución de un agente específico con código de Python. Te permiten observar, personalizar e incluso controlar el comportamiento del agente en puntos específicos predefinidos.

Hay una variedad de tipos de devoluciones de llamada que puedes utilizar, en los que cada tipo de devolución de llamada se ejecuta en un punto específico del turno de conversación.

Para este instructivo, agrega un mensaje estático a la respuesta del modelo cuando finalice la sesión:

  1. Haz clic en la barra de título del agente de despedida.
  2. Haz clic en Agregar devolución de llamada.
  3. Selecciona Después de LLM.

  4. Ingresa el siguiente código:

    SURVEY_MESSAGE = "Click here to take our post call survey."

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call('end_session'):
      return LlmResponse.from_parts(parts=[
        *llm_response.content.parts,
        Part.from_text(SURVEY_MESSAGE)

    ])
  return None

  5. Haz clic en Listo.

  6. Haz clic en Guardar.

Puedes volver a probar el agente para verificar el comportamiento de finalización de la sesión:

  1. Haz clic en Iniciar conversación nueva en la barra de título del simulador.
  2. Ingresa "Hola".
  3. Ingresa "Adiós".

Ten en cuenta que el agente ahora responde con tu mensaje agregado.

Instrucciones de estructura

Para mejorar el comportamiento del agente, puedes estructurar todas las instrucciones del agente en un formato XML de forma libre que sea óptimo para el procesamiento del modelo. Realiza lo siguiente para cada uno de tus agentes:

  1. Abre el panel de instrucciones de un agente.
  2. Haz clic en el botón Estructura en la parte superior derecha.
  3. Haz clic en Guardar.

Implementar

Una vez que tengas un agente en funcionamiento, tendrás varias opciones de implementación.