Exécution de code Python

Aperçu

L'outil Python Code Execution vous permet d'écrire et d'exécuter des fonctions Python personnalisées en tant que compétences réutilisables dans Swiftask. Au lieu de construire des flux de travail complexes avec des étapes prédéfinies, vous pouvez définir votre propre logique Python et faire exécuter par votre agent chaque fois que nécessaire. Ceci est utile pour la transformation de données, l'intégration d'API, les calculs ou toute logique métier personnalisée.

Comparaison avec l'interpréteur de code Python :

L'interpréteur de code Python permet aux agents de générer et d'exécuter du code Python dynamiquement sans fonctions prédéfinies. En revanche, Python Code Execution vous oblige à définir une fonction spécifique à l'avance avec des paramètres et une structure fixes. Choisissez Python Code Execution pour les tâches répétitives et prêtes pour la production avec des entrées cohérentes ; utilisez l'interpréteur de code Python pour les demandes flexibles et ad-hoc qui nécessitent une génération de code dynamique.

Prérequis

• Accès à l'interface de gestion des compétences Swiftask

• Connaissance de base de la syntaxe Python et de la définition des fonctions

• Compréhension des packages Python que votre fonction nécessite (le cas échéant)

• Pour les appels d'API ou l'accès aux données externes, assurez-vous d'avoir des identifiants valides et un accès réseau

Guide étape par étape

Étape 1 : Accéder à Python Code Execution

Dans la section des compétences, sélectionnez Python Code Execution parmi les catégories d'outils disponibles.

Étape 2 : Entrer un nom d'outil

Dans le champ Tool Name, fournissez un nom descriptif pour votre outil (par exemple, "Convert Currency", "Calculate Discount", "Parse JSON"). Ce nom apparaîtra quand l'agent sélectionnera cette compétence.

Étape 3 : Écrire une description de compétence

Dans le champ Skill Description, expliquez ce que cet outil fait et quand il doit être utilisé. Soyez clair sur l'objectif de l'outil pour que l'agent comprenne quand l'invoquer. Exemple : "Utilisé pour convertir les montants entre différentes devises en utilisant les taux de change en direct."

Étape 4 : Lister les packages Python requis (le cas échéant)

Dans le champ Python Packages, listez les bibliothèques Python externes dont votre code a besoin, séparées par des virgules. Laissez ce champ vide si votre code utilise uniquement les modules intégrés de Python. Exemple : requests, pandas, numpy

Étape 5 : Définir les paramètres de fonction (facultatif)

Dans le champ Python Function Parameters, fournissez un objet JSON décrivant chaque paramètre accepté par votre fonction. Chaque paramètre doit inclure :

• name: Le nom du paramètre (correspond à votre définition de fonction)

• type: Le type Python (par exemple, str, float, int, bool, list, dict)

• description: Ce que représente ce paramètre

  Si votre fonction n'a pas de paramètres, laissez ce champ vide ou entrez {}.

Exemple avec paramètres :

{
  "amount": {
    "name": "amount",
    "type": "float",
    "description": "The amount to convert"
  },
  "from_currency": {
    "name": "from_currency",
    "type": "str",
    "description": "Source currency code (e.g. USD)"
  },
  "to_currency": {
    "name": "to_currency",
    "type": "str",
    "description": "Target currency code (e.g. EUR)"
  }
}

Étape 6 : Écrire votre fonction Python

Dans le champ Python Code, collez votre fonction Python complète. Vous pouvez inclure les imports en haut du bloc de code, en dehors de la définition de la fonction. Le code doit :

• Inclure tous les imports nécessaires en haut (par exemple, import requests)

• Contenir une définition de fonction Python valide (commencer par def function_name():)

• Retourner un résultat (utiliser l'instruction return)

• Gérer les erreurs avec grâce si nécessaire

Exemple :

import requests


def convert_currency(
    amount: float,
    from_currency: str,
    to_currency: str
) -> str:
    url = (
        f"https://api.frankfurter.app/latest"
        f"?amount={amount}"
        f"&from={from_currency}"
        f"&to={to_currency}"
    )

    response = requests.get(url, timeout=10)
    response.raise_for_status()

    data = response.json()
    converted = data["rates"][to_currency]

    return f"{amount} {from_currency} = {converted} {to_currency}"

Étape 7 : Tester votre outil

Cliquez sur le bouton Test connection pour valider votre code. Cela exécutera votre fonction avec des données d'exemple pour s'assurer qu'elle fonctionne correctement avant de l'attacher à un agent.

Étape 8 : Enregistrer l'outil

Une fois les tests réussis, cliquez sur Save pour stocker votre outil. Il est maintenant disponible pour une utilisation dans les flux de travail et les compétences des agents.

Cas d'usage pratiques

Cas 1 : Conversion de devises dans un flux de travail de réservation
Un agent de voyage doit convertir les prix dans la devise locale du client. Vous créez un outil Python Code Execution qui récupère les taux de change en direct et retourne le montant converti, que l'agent applique automatiquement aux devis.

Cas 2 : Transformation et validation de données
Un agent d'assistance à la clientèle reçoit une entrée utilisateur non structurée (par exemple, un numéro de téléphone dans divers formats). Votre outil Python normalise l'entrée, la valide et retourne un format standardisé pour le stockage en base de données.

Cas 3 : Calcul dynamique basé sur des conditions
Un agent de commerce électronique calcule les frais d'expédition en fonction du poids, de la destination et du transporteur. Votre fonction Python implémente des règles métier complexes (par exemple, des remises en gros, des tarifs basés sur des zones) qui seraient fastidieuses à configurer avec des étapes prédéfinies.

Cas 4 : Intégration d'API pour les données en temps réel
Votre agent doit récupérer les données météorologiques, les cours des actions ou les niveaux d'inventaire à partir d'une API externe. Un outil Python Code Execution enveloppe l'appel API, gère l'authentification, analyse la réponse et retourne des données propres au flux de travail.

Conseils et bonnes pratiques

• Gardez les fonctions ciblées : Chaque outil doit faire une chose bien. Évitez de créer une seule fonction massive qui gère plusieurs tâches sans rapport.

• Utilisez des noms de paramètres significatifs : Des noms de paramètres clairs aident l'agent à comprendre quelles données transmettre et rendent votre code auto-documenté.

• Ajoutez la gestion des erreurs : Utilisez des blocs try-except pour capturer les erreurs avec grâce et retourner des messages d'erreur utiles au lieu de planter.

• Testez avec des données réalistes : Avant d'enregistrer, utilisez le bouton Test connection avec les données réelles que votre agent rencontrera.

• Documentez votre code : Ajoutez des commentaires dans votre code Python pour expliquer la logique complexe, surtout si d'autres la maintiendront plus tard.

• Évitez les opérations longues : Gardez le temps d'exécution court ; les opérations longues peuvent expirer. Pour le traitement lourd, envisagez de le diviser en étapes plus petites.

• Utilisez les délais d'attente pour les appels d'API : Lors de l'appel d'API externes (comme dans l'exemple de conversion), définissez toujours un délai d'attente pour éviter de bloquer.

Dépannage

Problème : "Test connection failed" ou la fonction ne s'exécute pas

Cause : Erreur de syntaxe dans votre code Python ou imports manquants.

Solution : Vérifiez votre code pour les fautes de frappe, assurez-vous que tous les imports sont inclus et vérifiez que la définition de la fonction est correcte. Testez d'abord une fonction simple (par exemple, def test(): return "hello") pour confirmer que l'environnement fonctionne.

Problème : Erreur "Module not found"

Cause : Un package Python requis n'est pas listé dans le champ Python Packages ou n'est pas installé dans l'environnement.

Solution : Ajoutez le nom du package au champ Python Packages (par exemple, requests) et enregistrez. Le système l'installera avant d'exécuter votre fonction.

Problème : Les paramètres de fonction ne sont pas transmis correctement

Cause : Les noms de paramètres dans la définition JSON ne correspondent pas à votre signature de fonction, ou le format JSON n'est pas valide.

Solution : Assurez-vous que les noms de paramètres dans le JSON Python Function Parameters correspondent exactement aux noms de paramètres dans votre ligne def function_name(param1, param2):. Validez la syntaxe JSON à l'aide d'un validateur JSON.

Problème : Les appels d'API externes expirent

Cause : L'API est lente ou inaccessible, ou votre valeur de délai d'attente est trop courte.

Solution : Augmentez la valeur du délai d'attente dans votre appel requests (par exemple, timeout=30), vérifiez que le point de terminaison de l'API est correct et accessible, et vérifiez votre connectivité réseau.

Quand utiliser Python Code Execution par rapport à l'interpréteur de code Python

Ressources supplémentaires

• Interpréteur de code Python : pour la génération dynamique de code sans fonctions prédéfinies