Créez une application d'agent

Ce guide vous explique la procédure à suivre pour créer une application agentique de base capable de répondre aux requêtes des utilisateurs concernant la météo.

Avant de commencer

Veillez à suivre les instructions de configuration avant de consulter ce guide.

Créer une application d'agent

Créez une application d'agent et un agent racine :

  1. Ouvrez la console CX Agent Studio.
  2. Sélectionnez votre projet.
  3. Cliquez sur Create agent (Créer un agent) ou New agent (Nouvel agent).
  4. Indiquez "weather app" (application météo) comme nom de l'agent.
  5. Cliquez sur Create (Créer). Si c'est la première application agentique que vous créez pour le projet, la création peut prendre une à deux minutes. Le créateur d'agents s'affiche et un agent racine est créé pour vous.

Créer la hiérarchie d'agents

Cette application agentique utilisera trois agents :

  • L'agent racine pour saluer l'utilisateur et déléguer à d'autres sous-agents.
  • L'agent météo pour répondre aux questions liées à la météo.
  • L'agent d'adieu pour terminer la conversation.

L'agent racine est déjà créé, mais vous devez modifier ses paramètres :

  1. Cliquez sur la barre de titre de l'agent racine.
  2. Vous pouvez éventuellement modifier le nom de l'agent.
  3. Saisissez la description suivante : "Handles simple greetings and delegates to other agents" (Gère les salutations simples et délègue à d'autres agents).
  4. Cliquez sur Save (Enregistrer), puis fermez le panneau des paramètres.

Créez l'agent météo :

  1. Cliquez sur le bouton + en bas de l'agent racine.
  2. Cliquez sur Add new sub-agent (Ajouter un sous-agent).
  3. Cliquez sur la barre de titre du nouvel agent.
  4. Remplacez le nom par "Weather agent" (Agent météo).
  5. Saisissez la description suivante : "Handles any weather related questions from the user" (Gère toutes les questions de l'utilisateur liées à la météo).
  6. Cliquez sur Save (Enregistrer), puis fermez le panneau des paramètres.

De la même manière, créez un autre sous-agent de l'agent racine appelé "Farewell agent" (Agent d'adieu) avec la description "Handles user farewells and goodbyes" (Gère les adieux et les au revoir des utilisateurs).

Capture d'écran de la hiérarchie des agents

Créer un outil météo

Les outils permettent de connecter votre agent à des systèmes externes ou à du code intégré fourni à l'agent. Votre agent peut ainsi interagir avec d'autres systèmes pour récupérer, mettre à jour, mettre en forme ou analyser des informations.

Dans cette étape, vous allez créer un outil météo qui permet de récupérer des informations météorologiques. Dans le cadre de ce guide, cet outil dispose d'une réponse simulée pour l'utilisateur. Dans une application météo réelle, cet outil accéderait à un serveur externe pour obtenir des informations.

Créez l'outil météo :

  1. Cliquez sur le bouton "Outils" à droite du créateur d'agents.
  2. Cliquez sur + pour créer un outil pour l'application agentique.
  3. Cliquez sur Python code (Code Python).

  4. Collez le code suivant :

    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. Cliquez sur Create (Créer).

Vous devez maintenant ajouter cet outil à l'agent météo :

  1. Cliquez sur le bouton + dans la barre de titre de l'agent météo.
  2. Cliquez sur Add tool (Ajouter un outil).
  3. Sélectionnez l'outil météo.

Créer des instructions pour l'agent

Chaque agent dispose d'un ensemble d' instructions qui définissent ce qu'il doit faire.

Lorsque vous fournissez des instructions qui font référence à un agent, utilisez la syntaxe {@AGENT: Agent name}. Pour faire référence à des outils, utilisez {@TOOL: tool_name}.

Créez des instructions pour chaque agent :

  1. Cliquez sur le bouton + dans la barre de titre de l'agent racine.
  2. Cliquez sur Add instructions (Ajouter des instructions).

  3. Saisissez les instructions suivantes :

    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. Cliquez sur Create (Créer).

  5. De la même manière, ajoutez les instructions suivantes pour l'agent météo :

    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 la même manière, ajoutez les instructions suivantes pour l'agent d'adieu :

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

Tester l'agent

Votre application agentique est désormais prête à interagir à l'aide du simulateur :

  1. Dans l'angle inférieur gauche de l'écran de la console, cliquez sur la barre Preview agent (Prévisualiser l'agent) pour développer la fenêtre si elle ne l'est pas déjà.
  2. Saisissez "hello", puis appuyez sur Entrée. L'agent répond par une salutation générique.
  3. Saisissez "what is the weather in new york?", puis appuyez sur Entrée. L'agent répond avec des informations météorologiques.
  4. Saisissez "goodbye", puis appuyez sur Entrée. L'agent termine la conversation.

Utiliser des variables

Les variables servent à stocker et à récupérer les données de conversation pendant l'exécution. Elles permettent donc aux agents de mémoriser des informations d'un tour de conversation à l'autre, ce qui favorise des interactions plus contextuelles. Pour cet agent, vous allez créer une variable qui capture le nom de l'utilisateur.

Pour créer la variable :

  1. Cliquez sur le bouton "Variables" à droite du créateur d'agents.
  2. Cliquez sur Create a variable (Créer une variable) ou +.
  3. Saisissez "username" comme nom de la variable.
  4. Laissez le type sur Text (Texte).
  5. Cliquez sur Create (Créer).

Maintenant que vous avez défini la variable, vous devez définir un outil qui permet à l'agent de la modifier :

  1. Cliquez sur le bouton "Outils" à droite du créateur d'agents.
  2. Cliquez sur + pour créer un outil pour l'application agentique.
  3. Cliquez sur Python code (Code Python).

  4. Collez le code suivant :

    from typing import Optional

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

  5. Cliquez sur Create (Créer).

Ajoutez cet outil à l'agent racine :

  1. Cliquez sur le bouton + dans la barre de titre de l'agent racine.
  2. Cliquez sur Add tool (Ajouter un outil).
  3. Sélectionnez l'outil update_username.

Ajoutez la phrase suivante aux instructions de l'agent racine, qui fait référence à la variable à l'aide de la syntaxe {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.

Vous pouvez tester à nouveau l'agent pour vérifier l'utilisation de la variable :

  1. Cliquez sur Start new conversation (Démarrer une nouvelle conversation) dans la barre de titre du simulateur.
  2. Saisissez "Hello, my name is Frank" (Bonjour, je m'appelle Frank).
  3. Saisissez "How accurate is your information?" (Vos informations sont-elles exactes ?).

Notez que l'agent répond désormais en utilisant votre nom pour chaque réponse. Vous pouvez également développer les sections Steps (Étapes) de la conversation du simulateur, où vous pouvez vérifier l'exécution des outils, entre autres.

Contrôler la fin de la session

Par défaut, chacun de vos agents est configuré pour utiliser l'outil end_session système. Toutefois, vous pouvez améliorer la fiabilité et le contrôle de la fin de la session en créant des instructions explicites.

Supprimez les outils end_session des agents racine et météo en cliquant sur le x à côté de l'outil dans chaque agent. Cela garantit que seul votre agent d'adieu mettra fin à la session.

Ajoutez les éléments suivants aux instructions de votre agent d'adieu :

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

Utiliser un rappel pour appliquer un message statique à la fin de la session

Les rappels fournissent un mécanisme permettant de se connecter au processus d'exécution d'un agent spécifique à l'aide de code Python. Ils vous permettent d'observer, de personnaliser et même de contrôler le comportement de l'agent à des moments précis et prédéfinis.

Vous pouvez utiliser différents types de rappels, chacun étant exécuté à un moment précis du tour de conversation.

Pour ce tutoriel, ajoutez un message statique à la réponse du modèle lorsque vous mettez fin à la session :

  1. Cliquez sur la barre de titre de l'agent d'adieu.
  2. Cliquez sur Add callback (Ajouter un rappel).
  3. Sélectionnez After LLM (Après le LLM).

  4. Saisissez le code suivant :

    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. Cliquez sur Done (OK).

  6. Cliquez sur Save (Enregistrer).

Vous pouvez tester à nouveau l'agent pour vérifier le comportement de fin de session :

  1. Cliquez sur Start new conversation (Démarrer une nouvelle conversation) dans la barre de titre du simulateur.
  2. Saisissez "Hello" (Bonjour).
  3. Saisissez "Goodbye" (Au revoir).

Notez que l'agent répond désormais en utilisant le message que vous avez ajouté.

Structurer les instructions

Pour améliorer le comportement de l'agent, vous pouvez structurer toutes les instructions de l'agent dans un format XML libre, optimal pour le traitement des modèles. Procédez comme suit pour chacun de vos agents :

  1. Ouvrez le panneau d'instructions d'un agent.
  2. Cliquez sur le bouton Structure en haut à droite.
  3. Cliquez sur Save (Enregistrer).

Déployer

Une fois que vous disposez d'un agent fonctionnel, vous avez plusieurs options de déploiement.