Différentes manières d'envoyer des requêtes à un agent Swiftask

Vue d'ensemble

Swiftask propose plusieurs canaux pour envoyer des requêtes à vos agents IA. Vous pouvez vous connecter par programmation via les API développeur, déclencher des tâches automatisées en arrière-plan via des webhooks externes, échanger via les canaux d'équipe et par e-mail, ou intégrer des widgets de chat orientés client directement sur votre site web.

Chaque canal répond à des besoins architecturaux précis, allant des échanges par e-mail sans code aux intégrations de streaming à fort débit. Les canaux Discord et vocaux restent exclus de ce guide en tant que fonctionnalités non destinées aux requêtes ou internes.

Prérequis

Avant d'envoyer des requêtes à vos agents Swiftask, assurez-vous de disposer des éléments suivants :

• Un compte Swiftask actif avec les autorisations nécessaires pour créer ou gérer des agents.

• Un agent existant configuré avec des instructions, un modèle sélectionné et des compétences optionnelles.

• Le slug de l'agent et le jeton client de l'agent accessibles dans Paramètres de l'agent → Déploiement → API (ou une clé API de compte depuis la section API de votre profil).

• Les autorisations sur les plateformes externes selon les cas (accès administrateur à l'espace Slack, compte développeur Meta ou accès au code source du site web).

Guide étape par étape

Méthode 1 : SDK OpenAI (recommandé)

La méthode par SDK OpenAI constitue le chemin d'intégration le plus rapide pour les développeurs disposant déjà d'implémentations IA. Swiftask expose un point de terminaison compatible OpenAI fonctionnant directement avec les bibliothèques clientes officielles d'OpenAI (Python, Node.js, TypeScript).

1. Générez votre clé API de compte depuis les paramètres API de votre profil.

2. Repérez le slug de votre agent sous Paramètres de l'agent → Déploiement → API.

3. Pointez votre client OpenAI vers l'URL de base https://api.swiftask.fr/v1 et transmettez le slug de votre agent comme valeur du paramètre model.

Appel standard en Python :

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.swiftask.fr/v1"
)

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[{"role": "user", "content": "Analysez notre rapport trimestriel."}]
)

print(response.choices[0].message.content)

Appel en streaming en Python :

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[{"role": "user", "content": "Générez un résumé."}],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Méthode 2 : API REST directe

L'API REST directe offre un accès HTTP programmatique sans dépendance logicielle externe. Cette solution est idéale pour les architectures backend sur mesure, les fonctions serverless ou les langages ne disposant pas de SDK dédié.

1. Récupérez le jeton client et le slug de l'agent sous Paramètres de l'agent → Déploiement → API.

2. Envoyez une requête HTTP POST à https://graphql.swiftask.ai/api/ai/VOTRE_SLUG_AGENT.

3. Fournissez l'en-tête d'autorisation et les paramètres du corps JSON.

Exemple cURL :

curl -X POST 'https://graphql.swiftask.ai/api/ai/YOUR_AGENT_SLUG' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx' \
  -d '{
    "input": "Résumez le rapport d incident #402.",
    "sessionId": 12345,
    "messageHistory": [],
    "files": [],
    "documentAnalysisMode": "SIMPLE",
    "extraConfig": {
      "analysisDepth": "detailed",
      "includeReferences": true
    }
  }'

Paramètres de requête :

Méthode 3 : Déclencheurs webhook

Les déclencheurs webhook permettent aux plateformes externes de démarrer des automatisations d'agent dès qu'un événement survient.

1. Ouvrez votre agent et sélectionnez Automatisations → Déclencheurs dans le menu de gauche.

2. Consultez le tableau de bord des déclencheurs affichant l'adresse e-mail dédiée et vos déclencheurs actifs.

3. Cliquez sur le bouton rouge + Nouveau déclencheur en haut à droite.

4. Sélectionnez Webhook ("Déclenchement par URL webhook HTTP. Parfait pour intégrer des services externes.").

5. Renseignez un Nom du déclencheur descriptif puis cliquez sur Suivant pour vérifier.

6. Cliquez sur Créer le déclencheur pour enregistrer la configuration.

7. Cliquez sur la carte du déclencheur créé dans la liste pour ouvrir le panneau latéral Détails du déclencheur et copier votre URL du webhook (POST) unique (https://graphql.swiftask.ai/api/agent-automation/webhook/[unique-id]).

Exemple d'appel du webhook :

curl -X POST https://graphql.swiftask.ai/api/agent-automation/webhook/[unique-id] \
  -H "Content-Type: application/json" \
  -d '{
    "data": "Customer feedback form submission payload"
  }'

Méthode 4 : Communication directe par e-mail

Chaque agent Swiftask reçoit une adresse e-mail dédiée pour le traitement asynchrone des messages et l'ingestion de documents.

1. Ouvrez votre agent et rendez-vous dans Automatisations → Déclencheurs.

2. Repérez l'adresse e-mail unique de l'agent au format agent-slug@agent.swiftask.ai.

3. Envoyez un e-mail à cette adresse ou mettez en place des règles de transfert automatique dans Gmail ou Outlook.

Gestion des fils de discussion et des pièces jointes :

• Contexte des fils : Lorsque les utilisateurs répondent dans le même fil de discussion, Swiftask suit les échanges. L'agent préserve le contexte au fil des réponses sans réinitialiser sa mémoire.

• Traitement des pièces jointes : Les documents, tableaux et images joints aux e-mails (PDF, DOCX, XLSX, images) sont automatiquement extraits et transmis au raisonnement de l'agent.

• Réponses automatisées : Les réponses sont renvoyées à l'expéditeur et les historiques d'échange sont consultables dans le chat du propriétaire de l'agent.

[Screenshot: Automations → Triggers dashboard displaying agent-slug@agent.swiftask.ai]

Méthode 5 : Intégration Slack via l'API Events

L'intégration Slack permet aux membres de votre équipe d'interagir avec les agents directement dans les canaux et messages privés Slack.

1. Créez une application personnalisée sur api.slack.com/apps.

2. Dans OAuth & Permissions, ajoutez l'URL de redirection : GET [backend_url]/slack/oauth_redirect.

3. Configurez les permissions de bot (scopes) requises (app_mentions:read, chat:write, channels:history, et im:history).

4. Dans Event Subscriptions, activez les événements et saisissez l'URL de requête : POST [backend_url]/slack/events.

5. Validez le défi de vérification d'URL (challenge), abonnez l'application aux événements de bot (app_mention, message.im), puis installez l'application dans votre espace de travail.

Une fois en place, les collaborateurs peuvent mentionner l'agent via @nom-de-l-agent dans n'importe quel canal pour obtenir des réponses instantanées.

Méthode 6 : Facebook Messenger via webhook de page dédié

Les agents peuvent traiter les messages reçus sur vos pages professionnelles Facebook via un webhook système dédié.

1. Rendez-vous dans les paramètres de votre application Meta sur le portail Meta for Developers.

2. Dans la configuration de Messenger, renseignez l'URL du webhook de page dédiée fournie par Swiftask.

3. Renseignez votre jeton de vérification pour valider le handshake de webhook de Meta.

4. Abonnez le webhook aux événements de page messages et messaging_postbacks.

Dès qu'un client contacte votre page Facebook, Meta relaie l'événement au webhook et l'agent répond directement dans la conversation Messenger de l'utilisateur.

Méthode 7 : Widget de chat intégrable

Le widget intégrable permet de déployer une fenêtre de conversation dynamique sur tout site web externe.

1. Ouvrez votre agent, déroulez Déploiement dans le menu de gauche, puis cliquez sur Bulle de chat (Widget).

2. Activez le bouton bascule Activer le widget.

3. Définissez l'apparence visuelle, l'avatar, l'emplacement et les suggestions de questions initiales.

4. Copiez le script d'intégration et insérez-le avant la balise fermante </body> de votre site web.

Authentification par jeton client :

Pour concevoir votre propre interface, échangez le jeton client de l'agent (depuis Déploiement → API) contre une session temporaire :

curl -X GET 'https://graphql.swiftask.ai/public/widget-bot/VOTRE_CLIENT_TOKEN' \
  -H 'x-client-uuid: VOTRE_CLIENT_UUID_UNIQUE'

Collecte continue des retours utilisateurs (feedback) :

• Notations : Des boutons pouce levé et pouce baissé s'affichent automatiquement sur chaque réponse de l'agent.

• Suivi qualité : Les évaluations et commentaires sont centralisés dans un tableau de bord en lecture seule, consultables, exportables ou supprimables par les responsables.

• Alertes e-mail : Les administrateurs peuvent paramétrer des notifications e-mail pour être avertis dès qu'un utilisateur soumet un retour.

Tableau comparatif des canaux

Cas d'usage pratiques

Traitement asynchrone des factures par e-mail

Des fournisseurs transmettent leurs factures à accounts-payable@agent.swiftask.ai. L'agent lit le fichier PDF joint, extrait les montants, répond aux questions du fournisseur dans le même fil et consigne les données traitées dans le logiciel comptable.

Support interne d'ingénierie sur Slack

Les développeurs mentionnent @ops-assistant dans un canal Slack pour consulter les procédures opérationnelles. L'agent répond dans le fil du canal, évitant les changements d'application.

Widget en libre-service avec suivi de satisfaction

Une entreprise déploie le widget sur sa page de tarifs. Les visiteurs posent des questions pré-achat et le responsable des ventes analyse la satisfaction dans le tableau de bord des retours tout en recevant des alertes e-mail en cas d'avis négatif.

Conseils et bonnes pratiques

• Sécurisez vos identifiants d'API : Stockez systématiquement vos jetons et clés API dans des variables d'environnement côté serveur. Ne les exposez jamais dans le code client public.

• Exploitez extraConfig pour vos métadonnées : Renseignez des identifiants d'organisation, des niveaux de permissions ou des indicateurs personnalisés dans extraConfig lors des appels REST afin d'adapter le comportement de l'agent.

• Activez la limitation de débit sur le widget : Configurez la limite de messages dans les options avancées du widget pour prévenir les abus et maîtriser la consommation de crédits.

• Définissez des règles de transfert d'e-mail : Transférez vos boîtes partagées (ex. support@entreprise.com) vers l'adresse dédiée de l'agent (agent-slug@agent.swiftask.ai) en veillant à conserver les en-têtes RFC de fil de discussion.

Dépannage

Les appels webhook renvoient une erreur 400 ou échouent

• Cause : Le corps de la requête HTTP n'est pas un JSON valide ou l'en-tête Content-Type est absent.

• Solution : Vérifiez la présence de l'en-tête Content-Type: application/json et validez la structure du payload JSON.

Les réponses par e-mail perdent le fil de la discussion

• Cause : Le serveur d'envoi ou la règle de redirection supprime les en-têtes In-Reply-To et References.

• Solution : Assurez-vous que votre messagerie ou règle de transfert préserve les en-têtes de discussion standard lors de l'envoi vers agent-slug@agent.swiftask.ai.

La vérification d'URL des événements Slack échoue

• Cause : Votre serveur n'a pas répondu au défi initial url_verification de Slack en renvoyant le paramètre brut challenge.

• Solution : Vérifiez que le point de terminaison de l'URL de requête Slack renvoie immédiatement la chaîne du challenge lors de la réception de l'événement de vérification.

Ressources complémentaires

• Accéder aux agents Swiftask via le SDK OpenAI – Guide d'implémentation pour les SDK Python et JavaScript.

• Accéder à l'IA et aux agents via l'API – Référence technique des points de terminaison REST et GraphQL.

• Déclencheurs webhook – Instructions de configuration des webhooks d'automatisation entrants.

• Communication directe par e-mail avec les agents IA – Mise en place d'une boîte de réception pour votre agent.

• Intégration et widget – Personnalisation et déploiement des bulles de chat sur site web.