L'API Assistant prend en charge l'appel de fonction. Cette fonctionnalité permet à un agent d'invoquer automatiquement des fonctions externes pour accomplir des tâches, telles que la traduction de texte. Cette rubrique s'appuie sur un exemple simple d'« Agent de traduction » pour vous aider à comprendre rapidement les principes fondamentaux de l'appel de fonction.
Démarrage rapide
Dans cet exemple, vous créez un agent de traduction ainsi qu'une fonction nommée translate_text que l'agent peut appeler. Vous demandez ensuite à l'agent de traduire « Hello world » en chinois.
Prérequis
Installez les bibliothèques de dépendances requises, telles que requests et dashscope, en exécutant la commande suivante :
Étape 1 : Créer la fonction « translate_text »
Commencez par créer une fonction de traduction simple. À des fins de démonstration, cette fonction utilise une table de traduction prédéfinie.
- Fonctionnalité de traduction : Simule une capacité de traduction via une table prédéfinie prenant en charge la conversion entre plusieurs langues.
- Gestion des erreurs : La fonction intègre un mécanisme basique de gestion des erreurs afin de garantir une réponse appropriée en toutes circonstances.
translate_text définie précédemment pour fournir des services de traduction.
Étape 2 : Décrire la fonction « translate_text »
Décrivez la fonction translate_text à l'agent. Ce dernier s'appuie sur cette description pour invoquer correctement la fonction.
- name : Nom de la fonction (
translate_text). L'agent utilise cet identifiant pour l'appeler. - description : Description de l'outil aidant l'agent à en comprendre l'utilité.
- parameters : Définit les paramètres de la fonction, comprenant le texte à traduire et la langue cible.
Étape 3 : Créer un agent
Créez maintenant une instance Assistant. Cette instance agit comme un agent exploitant l'outil de traduction défini.
- model : Spécifie le modèle à utiliser. Cet exemple emploie
qwen-plus, capable de comprendre le langage naturel et de traiter des tâches. - name : Nom de l'agent. Définissez la valeur sur « Translation Assistant ».
- description : Décrit l'objectif de l'agent, à savoir aider les utilisateurs à traduire du texte.
- tools : Enregistre le
translation_tooldéfini précédemment, autorisant ainsi l'agent à l'invoquer.
Étape 4 : Créer un fil de conversation et interagir avec l'agent
Créez un nouveau fil de conversation, ajoutez-y un message utilisateur, puis lancez l'agent pour traiter la requête.
- Threads.create() : Initialise un nouveau fil de conversation pour les messages suivants.
- Messages.create() : Ajoute un message utilisateur au fil. Ici, l'utilisateur demande la traduction de « Hello world » en chinois.
- Runs.create() : Déclenche le traitement du message utilisateur par l'agent.
- Runs.wait() : Attend la fin du traitement par l'agent.
Étape 5 : Gérer l'appel de fonction et retourner le résultat
Si l'agent doit invoquer un outil durant son traitement, la fonction translate_text est appelée et le résultat est retourné.
- Vérification de l'appel de fonction : Si l'agent nécessite un appel de fonction, votre code vérifie si la fonction demandée est
translate_text, puis exécute la traduction via la fonction définie plus haut. - Soumission du résultat : Transmettez le résultat de la traduction à l'agent via
Runs.submit_tool_outputs, puis attendez sa prochaine réponse.
Étape 6 : Obtenir la réponse de l'agent
Une fois le traitement terminé, récupérez la réponse de l'agent depuis le fil de conversation pour l'afficher à l'utilisateur.
Résumé
En suivant ces étapes, vous avez créé un agent capable de gérer les demandes de traduction des utilisateurs et d'utiliser une fonction dédiée pour convertir du texte. L'API Assistant simplifie la conception d'agents complexes orientés tâches.
Vous pouvez étendre les fonctionnalités de l'agent selon vos besoins, notamment en ajoutant d'autres outils ou en modifiant ses instructions comportementales.
Générer rapidement des descriptions pour les fonctions métier
Dans l'exemple de démarrage rapide, vous devez décrire la fonction « translate_text » à l'agent, ce qui peut s'avérer fastidieux. Nous fournissons donc une fonction de conversion simple pour décrire rapidement vos fonctions métier.
translate_text du démarrage rapide :
translate_text est automatiquement convertie en :
Utiliser la sortie en streaming
Lorsque vous utilisez la sortie en streaming, modifiez la logique du code présentée à l'Étape 5 : Gérer l'appel de fonction et retourner le résultat. En effet, l'objet Runs retourne désormais un flux d'événements Assistant.
Quand l'Assistant décide d'appeler une fonction, l'objet Runs émet l'événement thread.run.requires_action ainsi que les paramètres d'entrée data.required_action.submit_tool_outputs.tool_calls fournis par le grand modèle de langage (LLM). Soumettez alors la sortie de la fonction.
Notez que vous devez également activer la sortie en streaming lors de la soumission du résultat de la fonction avec run = Runs.submit_tool_outputs.
while supplémentaire englobe la boucle for traitant le flux d'événements. Le système génère en effet un nouvel objet Runs lorsque vous soumettez la sortie de la fonction. La boucle while suit automatiquement le dernier flux d'événements, permettant à l'Assistant de poursuivre la génération de sa réponse après réception du résultat de l'appel de fonction.