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
Crea una aplicación de agente y un agente raíz:
- Abre la consola de CX Agent Studio.
- Selecciona o crea tu proyecto.
- Haz clic en Crea tu primer agente de IA o Crear agente.
- Proporciona "weather app" como el nombre del agente.
- Haz clic en Crear. Si esta 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 creador de agentes y se crea un agente raíz para ti.
Crea la jerarquía de agentes
Esta aplicación de agente usará tres agentes:
- Agente raíz para saludar al usuario y delegar tareas a otros agentes secundarios
- Agente meteorológico para responder preguntas relacionadas con el clima.
- Agente de despedida para completar la conversación.
Ya se creó el agente raíz, pero debes actualizar su configuración:
- Haz clic en la barra de título del agente raíz.
- De manera opcional, puedes cambiar el nombre del agente.
- Ingresa la descripción: "Handles simple greetings and delegates to other agents".
- Haz clic en Guardar y, luego, cierra el panel de configuración.
Crea el agente del clima:
- Haz clic en el botón + en la parte inferior del agente raíz.
- Haz clic en Agregar nuevo agente secundario.
- Haz clic en la barra de título del agente nuevo.
- Cambia el nombre a "Weather agent".
- Ingresa la descripción: "Handles any weather related questions from the user".
- Haz clic en Guardar y, luego, cierra el panel de configuración.
De manera similar, crea otro agente secundario del agente raíz llamado "Farewell agent" con la descripción "Handles user farewells and goodbyes".

Crea una herramienta meteorológica
Las herramientas se usan para conectar tu agente a sistemas externos o código intercalado proporcionado al agente. 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 de clima, que se usa para recuperar información meteorológica. Para los fines 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.
Crea la herramienta de clima:
- Haz clic en el botón de herramientas que se encuentra en el lado derecho del compilador de agentes.
- Haz clic en + para crear una herramienta nueva para la aplicación del agente.
- Haz clic en Código de Python.
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}'."}Haz clic en Crear.
Ahora, debes agregar esta herramienta al agente del clima:
- Haz clic en el botón + en la barra de título del agente meteorológico.
- Haz clic en Agregar herramienta.
- Selecciona la herramienta de clima.
Crea instrucciones para el 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 las herramientas de referencia, usa {@TOOL: tool_name}.
Crea instrucciones para cada agente:
- Haz clic en el botón + en la barra de título del agente raíz.
- Haz clic en Agregar instrucciones.
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.Haz clic en Crear.
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.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:
- 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.
- Escribe "hello" y, luego, presiona Intro. El agente responde con un saludo genérico.
- Escribe "¿Cómo está el clima en Nueva York?" y, luego, presiona Intro. El agente responde con información sobre el clima.
- Escribe "goodbye" 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, sigue estos pasos:
- Haz clic en el botón de variables que se encuentra en el lado derecho del compilador de agentes.
- Haz clic en Crear una variable o +.
- Escribe "username" como nombre de la variable.
- Deja el tipo como Texto.
- Haz clic en Crear.
Ahora que definiste la variable, debes definir una herramienta que permita al agente actualizarla:
- Haz clic en el botón de herramientas que se encuentra en el lado derecho del compilador de agentes.
- Haz clic en + para crear una herramienta nueva para la aplicación del agente.
- Haz clic en Código de Python.
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)Haz clic en Crear.
Agrega esta herramienta al agente raíz:
- Haz clic en el botón + en la barra de título del agente raíz.
- Haz clic en Agregar herramienta.
- 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 variables:
- Haz clic en Iniciar nueva conversación en la barra de título del simulador.
- Ingresa "Hello, my name is Frank".
- Ingresa "¿Qué tan precisa es tu información?".
Observa que el agente ahora responde usando 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 herramienta del sistema
end_session.
Sin embargo,
puedes mejorar la confiabilidad y el control de cómo finalizar la sesión
creando instrucciones explícitas.
Quita las herramientas de end_session de los agentes raíz y del clima
haciendo clic en la x junto a la herramienta en cada agente.
Esto garantiza que solo el agente de despedida finalice 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 de manera forzosa 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 varios tipos de devoluciones de llamada que puedes usar, 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 finalices la sesión:
- Haz clic en la barra de título del agente de despedida.
- Haz clic en Agregar devolución de llamada.
- Selecciona Después del LLM.
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 NoneHaz clic en Listo.
Haz clic en Guardar.
Puedes volver a probar el agente para verificar el comportamiento de finalización de la sesión:
- Haz clic en Iniciar nueva conversación en la barra de título del simulador.
- Ingresa "Hello".
- Ingresa "Goodbye".
Observa que el agente ahora responde con el mensaje que agregaste.
Instrucciones de estructura
Para mejorar el comportamiento del agente, puedes estructurar todas sus instrucciones en un formato XML de formato libre que sea óptimo para el procesamiento del modelo. Realiza las siguientes acciones para cada uno de tus agentes:
- Abre el panel de instrucciones de un agente.
- Haz clic en el botón Structure en la parte superior derecha.
- Haz clic en Guardar.
Implementar
Una vez que tengas un agente en funcionamiento, tendrás varias opciones de implementación.