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

Écrit par Stanislas

Dernière mise à jour Il y a 14 jours

Aperçu

Swiftask offre plusieurs méthodes pour envoyer des requêtes à vos agents IA. Chaque approche est optimisée pour différents cas d'usage : intégrations dans des applications existantes, automations externes, ou interactions par email. Vous pouvez choisir la méthode qui correspond le mieux à votre architecture et vos besoins.

1. SDK OpenAI (Méthode recommandée)

Ce que c'est

La méthode la plus simple et la plus flexible. Vos agents Swiftask sont compatibles avec les SDKs OpenAI officiels (Python, JavaScript, Node.js, TypeScript, etc.). Vous pouvez utiliser le code OpenAI que vous connaissez déjà, mais en le pointant vers Swiftask.

Quand l'utiliser

  • Vous avez déjà du code OpenAI et voulez réutiliser les mêmes patterns

  • Vous intégrez des agents dans des applications existantes

  • Vous traitez des documents en batch avec Python ou JavaScript

  • Vous voulez du streaming en temps réel pour une meilleure UX

Configuration

URL de base : https://api.swiftask.fr/v1

Authentification : Clé API Swiftask (disponible dans Account Settings → API)

Paramètre modèle : Slug de votre agent (disponible dans Agent Settings → API tab)

Exemple 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": "Bonjour, comment pouvez-vous m'aider ?"}]
)

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

Exemple JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'YOUR_API_KEY',
    baseURL: 'https://api.swiftask.fr/v1',
});

const response = await client.chat.completions.create({
    model: 'AGENT_SLUG',
    messages: [{ role: 'user', content: 'Bonjour, comment pouvez-vous m\'aider ?' }]
});

console.log(response.choices[0].message.content);

Avec streaming (temps réel)

# Python avec streaming
response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[{"role": "user", "content": "Analyse ce document"}],
    stream=True
)

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

Documentation complète : Access Swiftask agents via OpenAI SDK (recommended)

2. Accès API direct (REST)

Ce que c'est

Accès direct à l'API REST Swiftask pour les développeurs qui préfèrent travailler sans SDK. Vous envoyez des requêtes HTTP POST directement aux endpoints Swiftask.

Quand l'utiliser

  • Vous préférez les requêtes HTTP brutes sans SDK

  • Vous travaillez dans un langage non supporté par OpenAI SDK

  • Vous avez des besoins très spécifiques en termes d'authentification

  • Vous intégrez avec des systèmes legacy

Configuration

Endpoint : POST https://api.swiftask.fr/admin/agent/create

Headers :

Authorization: Bearer YOUR_API_KEY
Content-Type: application/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": "Bonjour, comment pouvez-vous m\'aider ?",
    "sessionId": 12345,
    "messageHistory": [],
    "files": [],
    "documentAnalysisMode": "SIMPLE"
  }'

Paramètres principaux

Paramètre

Type

Requis

Description

input

string

Oui

Le message à envoyer à l'agent

sessionId

number

Oui

ID de session pour maintenir le contexte

messageHistory

array

Non

Historique des messages précédents

files

array

Non

Fichiers à analyser (documents, images)

documentAnalysisMode

string

Non

Mode d'analyse : SIMPLE ou ADVANCED

Documentation complète : Access AI and Agent through API

3. Webhook Triggers (Automations externes)

Ce que c'est

Un endpoint HTTP unique pour votre agent. Les systèmes externes envoient des données POST à cet endpoint, et votre agent se déclenche automatiquement pour traiter les données. Idéal pour les intégrations avec des services externes.

Quand l'utiliser

  • Un système externe doit déclencher votre agent (Zendesk, Typeform, Stripe, etc.)

  • Vous avez besoin d'automations basées sur des événements externes

  • Vous intégrez avec des outils sans-code (Zapier, Make, etc.)

  • Vous traitez des webhooks provenant de services tiers

Configuration

Créer un webhook trigger

  1. Accédez à l'agent que vous souhaitez automatiser

  2. Dans la barre latérale, localisez la section Automatisation

  3. Cliquez sur Déclencheurs (marqué comme NEW)

  4. Cliquez sur le bouton Nouveau déclencheur (bouton rouge avec icône +)

  5. Une boîte de dialogue s'ouvre avec les options de type de trigger

  6. Sélectionnez Webhook ("Trigger via HTTP webhook URL. Perfect for integrating with external services.")

  7. Entrez un Nom du déclencheur descriptif (ex: "Customer Support Ticket", "New Form Submission", "Payment Received")

  8. Cliquez sur Suivant pour vérifier votre configuration

  9. Cliquez sur Créer le déclencheur

Récupérer votre URL webhook

Une fois le trigger créé :

  1. Dans la liste des Triggers, trouvez votre webhook trigger

  2. Cliquez dessus pour ouvrir le panneau de détails

  3. Localisez le champ Webhook URL (POST)

  4. Copiez l'URL complète; c'est ce que vos systèmes externes appelleront

L'URL générée ressemble à ceci :

https://graphql.swiftask.ai/api/agent-automation/webhook/[unique-id]

Le [unique-id] est généré automatiquement par le système et propre à votre trigger.

Exemple d'envoi de données

curl -X POST https://graphql.swiftask.ai/api/agent-automation/webhook/[unique-id] \
  -H "Content-Type: application/json" \
  -d '{
    "data": "Données que vous voulez envoyer à l'\''agent"
  }'

Cas d'usage courants

1. Automatisation des tickets de support

  • Zendesk crée un ticket → Webhook déclenche votre agent → Agent répond automatiquement

2. Traitement de soumissions de formulaire

  • Typeform reçoit une soumission → Webhook déclenche votre agent → Agent catégorise et route la demande

3. Notifications de paiement

  • Stripe envoie une notification de paiement → Webhook déclenche votre agent → Agent met à jour la DB et envoie une confirmation

4. Enrichissement de données

  • CRM crée un lead → Webhook déclenche votre agent → Agent enrichit le lead avec des données externes

Documentation complète : Triggers from webhook

4. Communication par Email

Ce que c'est

Chaque agent reçoit une adresse email unique. Vous pouvez envoyer des emails directement à votre agent, qui les traite et répond automatiquement selon sa configuration.

Quand l'utiliser

  • Vous voulez que votre agent traite les emails entrants

  • Vous intégrez avec des systèmes de gestion d'emails (Gmail, Outlook, etc.)

  • Vous avez besoin de traiter automatiquement des documents envoyés par email

  • Vous voulez une approche sans-code pour déclencher votre agent

Configuration

Chaque agent a une adresse email unique (format: agent-slug@swiftask.ai). Vous la trouvez dans Configuration Agent →Déclencheurs.

Cas d'usage courants

1. Traitement de documents

  • Envoyez une facture par email → Agent traite automatiquement

2. Capture de leads

  • Email d'enquête → Agent qualifie le lead et met à jour le CRM

3. Triage du support client

  • Email de support → Agent catégorise et route vers l'équipe appropriée

4. Collecte de contenu

  • Envoyez des articles → Agent analyse et crée un résumé

5. Gestion d'événements

  • Email d'inscription → Agent traite l'inscription et envoie une confirmation

Capacités

  • Traite tous les formats d'email (texte brut, HTML, multipart)

  • Supporte les pièces jointes (documents, images, fichiers)

  • Gère les conversations par email (threads)

  • Génère des réponses intelligentes basées sur la base de connaissances

  • Multi-langue

Documentation complète : Communication directe par e-mail avec les agents IA

Tableau comparatif

Méthode

Cas d’usage

Complexité

Temps réel

Authentification

SDK OpenAI

Intégration d'apps

Basse

Oui (streaming)

Clé API

API REST directe

Requêtes brutes

Basse

Oui

Clé API

Webhook Triggers

Automations externes

Moyenne

Non

URL unique

Email

Traitement email

Très basse

Non

Adresse email unique

Bonnes pratiques de sécurité

  • Sécurisez vos clés API : Traitez-les comme des mots de passe. Utilisez des variables d'environnement, jamais du hardcode.

  • Définissez une date d'expiration : Lors de la création d'une clé API, définissez une date d'expiration pour la sécurité.

  • Nommez vos clés : Utilisez des noms descriptifs (ex : "Production Bot", "Testing Bot") pour suivre l'utilisation.

  • Rotez régulièrement : Changez vos clés API périodiquement.

Prochaines étapes

  1. Choisissez votre méthode en fonction de votre cas d'usage

  2. Consultez la documentation spécifique via les liens fournis

  3. Testez avec cURL ou Postman avant d'intégrer dans votre code

  4. Implémentez la gestion d'erreurs dans votre application

  5. Monitorez l'utilisation de vos crédits Swiftask