Créer un agent d'intelligence artificielle via l'API

Présentation

Le point de terminaison de l'API Create Agent vous permet de créer et de déployer des agents IA directement depuis votre application. Au lieu de configurer manuellement les agents dans l'interface Swiftask, vous pouvez automatiser la création d'agents à l'aide d'une seule requête REST. Cette solution est idéale pour les plateformes qui intègrent Swiftask, les produits SaaS nécessitant des agents en marque blanche, ou les équipes qui gèrent de nombreux agents sur différents projets.

Chaque agent que vous créez est un assistant IA complet et indépendant, doté de son propre nom, d'une invite système, d'objectifs, ainsi que de bases de connaissances et de compétences facultatives. Vous contrôlez chaque aspect via l'API.

Prérequis

Avant d'appeler l'API Create Agent, assurez-vous de disposer :

1. Un espace de travail Swiftask avec un forfait payant (Starter, Professional ou Enterprise)

2. Un rôle de propriétaire ou d'administrateur dans votre espace de travail

3. Une clé API (voir « Obtenir votre clé API » ci-dessous)

4. Des connaissances de base en HTTP – Compréhension des requêtes API REST et du format JSON

5. Informations requises sur l'agent :

• Nom de l'agent

• Description (en anglais)

• Description (français)

• Invite du système

• Message d'accueil (anglais)

• Message d'accueil (français)

Obtenir votre clé API

Pour authentifier les requêtes API, vous devez créer une clé API à partir des paramètres de votre compte :

• Cliquez sur les paramètres de votre compte dans le menu en bas à gauche

• Accédez aux paramètres du compte > API

• Cliquez sur « Créer une nouvelle clé API »

• Copiez la clé API générée et conservez-la en lieu sûr

Important : veillez à la sécurité de votre clé API. Toute personne y ayant accès peut effectuer des requêtes API au nom de votre compte et utiliser vos crédits. Traitez-la comme un mot de passe.

Guide étape par étape

Étape 1 : Préparez la configuration de votre agent

Définissez toutes les propriétés requises pour votre agent. L'API nécessite six champs obligatoires :

• name – Un nom clair et descriptif (par exemple, « Bot d'assistance client »)

• description – Description en anglais de ce que fait l'agent

• descriptionFR – Description en français de ce que fait l'agent

• systemPrompt – Instructions détaillées définissant le rôle, le comportement et les règles de l'agent

• greetingMessage – Message de bienvenue en anglais lorsque les utilisateurs lancent une conversation

• greetingMessageFR – Message de bienvenue en français lorsque les utilisateurs lancent une conversation

Exemple de configuration :

{  
   "name": "Customer Support Agent",  
   "description": "Handles customer inquiries and provides product information",  
   "descriptionFR": "Gère les demandes des clients et fournit des informations 
                     sur les produits",  
   "systemPrompt": "You are a helpful customer support specialist. Answer 
                    questions about our products with accuracy and 
                    professionalism. Always be polite and offer solutions. If you 
                    don't know the answer, ask the customer to contact our 
                    support team.",  
   "greetingMessage": "Hello! How can I help you today?",  
   "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?"
}

Étape 2 : Effectuer la requête API

Point de terminaison : POST https://api.swiftask.fr/admin/agent/create

En-têtes :

Authorization: Bearer {YOUR_API_KEY}
Content-Type: application/json

En-tête facultatif :

x-workspace-id: {workspaceId}

Important : l'en-tête x-workspace-id est facultatif. N'incluez-le que si vous souhaitez créer l'agent dans un espace de travail spécifique où vous disposez d'un accès Administrateur ou Propriétaire. Sans cet en-tête, l'agent sera créé dans votre espace de travail par défaut.

Corps de la requête (champs obligatoires uniquement) :

{  
   "name": "Customer Support Agent",  
   "description": "Handles customer inquiries and provides product information",  
   "descriptionFR": "Gère les demandes des clients et fournit des informations   
                     sur les produits",  
   "systemPrompt": "You are a helpful customer support specialist. Answer 
                     questions about our products with accuracy and 
                     professionalism. Always be polite and offer solutions. If 
                     you don't know the answer, ask the customer to contact our 
                     support team.",  
   "greetingMessage": "Hello! How can I help you today?",
   "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?"
}

Corps de la requête (avec champs facultatifs) :

{  
   "name": "Customer Support Agent",  
   "description": "Handles customer inquiries and provides product information",  
   "descriptionFR": "Gère les demandes des clients et fournit des informations 
                     sur les produits", 
   "systemPrompt": "You are a helpful customer support specialist. Answer 
                    questions about our products with accuracy and 
                    professionalism. Always be polite and offer solutions. If you 
                    don't know the answer, ask the customer to contact our 
                    support team.",  
   "greetingMessage": "Hello! How can I help you today?",  
   "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",  
   "profilePicture": "https://example.com/agent-avatar.png",  
   "departement": "Support",  
   "model": "gpt-4o",  
   "temperature": 0.7,  
   "ragRetrievalTopKChunk": 5, 
   "ragDefaultChunkSize": 512,  
   "enableMemorySession": true,   
   "questionStarter": [    
      "What are your office hours?",    
      "How do I reset my password?"  
    ]
}

Exemple complet de cURL :

curl -X POST \  https://graphql.swiftask.ai/admin/agent/create \  -H "Authorization: Bearer sk_YOUR_API_KEY_HERE" \  -H "Content-Type:  
 application/json" \  -d '{    
    "name": "Customer Support Agent",    
    "description": "Handles customer inquiries and provides product information",        
    "descriptionFR": "Gère les demandes des clients et fournit des informations 
                     sur les produits",    
    "systemPrompt": "You are a helpful customer support specialist. Answer 
                      questions about our products with accuracy and 
                      professionalism. Always be polite and offer solutions. If 
                      you do not know the answer, ask the customer to contact our 
                      support team.",
    "greetingMessage": "Hello! How can I help you today?",       
    "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",    
    "model": "gpt-4o",    
    "temperature": 0.7,    
    "enableMemorySession": true  
}'

Étape 3 : Traiter la réponse

Réponse de réussite (201) :

{  
   "success": true,  
   "data": {    
      "id": "agent_789",    
      "name": "Customer Support Agent",    
      "slug": "customer-support-agent-xyz",    
      "description": "Handles customer inquiries and provides product 
                      information",    
      "descriptionFR": "Gère les demandes des clients et fournit des informations 
                        sur les produits",    
      "systemPrompt": "You are a helpful customer support specialist...",      
      "greetingMessage": "Hello! How can I help you today?",    
      "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",    
      "createdAt": "2026-04-20T08:11:03.356Z",    
      "status": "active"  
   }
}

Enregistrez l'id et l'slug de l'agent pour de futurs appels API. L'slug est l'identifiant unique que vous utiliserez pour référencer cet agent.

Réponse d'erreur (400) :

{  
   "success": false,  
   "error": {    
      "code": "INVALID_REQUEST",    
      "message": "Missing required field: descriptionFR"  
    }
}

Champs API disponibles

L'API Create Agent prend en charge les champs suivants :

Champs obligatoires

Champs facultatifs

Recommandations de champs par cas d'utilisation

temperature – Contrôle la créativité des réponses :

• 0,0–0,3 : Déterministe (idéal pour le service client, les réponses aux FAQ)

• 0,4–0,7 : Équilibré (idéal pour les tâches générales, la valeur par défaut est 0,7)

• 0,8–1,0 : créatif (idéal pour le brainstorming, la création de contenu)

ragRetrievalTopKChunk – Nombre d'éléments de la base de connaissances à récupérer :

• Des valeurs plus élevées = plus de contexte, mais peuvent inclure des informations non pertinentes

• Recommandé : 5 dans la plupart des cas, 10 pour les sujets complexes

• Augmenter si les réponses sont incomplètes

ragDefaultChunkSize – Taille des segments de la base de connaissances :

• Plus élevée = segments plus grands avec plus de contexte par segment

• Plus faible = segments plus petits avec des informations plus ciblées

• La valeur par défaut de 512 convient à la plupart des documents

enableMemorySession – Permettre aux agents de mémoriser le contexte de la conversation :

• Utile pour les conversations à plusieurs tours et les interactions personnalisées

• Désactivez cette option pour les agents sans état (réponses aux FAQ) ou les applications sensibles en matière de confidentialité

questionStarter – Liste d'exemples de questions pour aider les utilisateurs :

"questionStarter": [  
     "What are your office hours?",  
     "How do I reset my password?",  
     "What products do you offer?"
]

Cas d'utilisation pratiques

Automatisation du service client

Créez un agent d'assistance en utilisant la documentation de votre produit comme base de connaissances. L'agent répond aux questions fréquentes, résout les problèmes et transmet les problèmes complexes à des agents humains.

{  
    "name": "Support Bot",  
    "description": "Answers customer questions about our product",   
    "descriptionFR": "Répond aux questions des clients sur notre produit",  
    "systemPrompt": "You are a support specialist. Use only the provided 
                     knowledge base to answer questions. If the answer is not in 
                     the knowledge base, tell the customer to contact 
                     support@company.com.",  
     "greetingMessage": "Hi! How can I help you?",  
     "greetingMessageFR": "Bonjour ! Comment puis-je vous aider ?",  
     "model": "gpt-4o",  
     "temperature": 0.3,  
     "enableMemorySession": true
}

Qualification des prospects

Créez un agent commercial qui qualifie les prospects en posant des questions de qualification et en recueillant leurs coordonnées.

{  
     "name": "Sales Qualification Bot",  
     "description": "Qualifies sales leads and collects information",       
     "descriptionFR": "Qualifie les prospects et collecte les informations",  
     "systemPrompt": "You are a sales specialist. Qualify leads by asking about  
                      their company size, industry, and budget. Be friendly and 
                      professional. Collect their name and email before ending 
                      the conversation.", 
     "greetingMessage": "Hi! I'm here to learn about your needs. What brings you 
                         here today?",  
     "greetingMessageFR": "Bonjour ! Je suis ici pour en savoir plus sur vos 
                           besoins. Qu'est-ce qui vous amène ?",  
     "model": "gpt-4o",  
     "temperature": 0.6,  
     "questionStarter": [    
              "Tell me about your company",    
              "What's your budget range?",    
              "When do you need this solution?"  ]
}

Assistant de connaissances interne

Créez un agent qui aide les employés à trouver des informations sur l'entreprise, les politiques et les procédures à partir de votre base de connaissances interne.

{  
    "name": "Internal Knowledge Assistant",  
    "description": "Helps employees find company information and policies",   
    "descriptionFR": "Aide les employés à trouver les informations et les 
                      politiques de l'entreprise",  
    "systemPrompt": "You are an internal knowledge assistant. Help employees find    
                     company policies, procedures, and information. Be helpful 
                     and accurate. Direct them to HR or management if they have 
                     questions outside your scope.",  
    "greetingMessage": "Hello! I'm here to help you find company information.",  
    "greetingMessageFR": "Bonjour ! Je suis ici pour vous aider à trouver les 
                          informations de l'entreprise.",  
    "model": "gpt-4o",  
    "temperature": 0.3,  
    "enableMemorySession": true,  
    "departement": "HR"
}

Dépannage

Erreur : « Champ obligatoire manquant : descriptionFR »

Cause : vous n'avez pas inclus le champ descriptionFR dans le corps de votre requête.

Solution : Ajoutez un champ « descriptionFR » contenant une description en français de votre agent. Exemple : "descriptionFR": "Un assistant utile pour répondre aux questions."

Erreur : « Champ obligatoire manquant : greetingMessageFR »

Cause : Vous n'avez pas inclus le champ greetingMessageFR dans le corps de votre requête.

Solution : ajoutez un champ « greetingMessageFR » contenant un message d'accueil en français. Exemple : "greetingMessageFR": "Bonjour ! Comment puis-je vous aider ?"

Erreur : « Jeton d'autorisation non valide »

Cause : votre clé API est manquante, a expiré ou est incorrecte.

Solution :

1. Vérifiez que vous avez bien créé la clé API dans la section Profil / Info-utilisateur → API / Développeur

2. Assurez-vous que la clé API est transmise dans l'en-tête Authorization: Bearer {API_KEY}

3. Vérifiez que vous avez correctement copié l'intégralité de la clé (sans espaces supplémentaires)

4. Créez une nouvelle clé API si celle-ci est compromise

Erreur : « En-tête manquant : Content-Type »

Cause : l'en-tête Content-Type est absent de votre requête.

Solution : ajoutez l'en-tête Content-Type: application/json à toutes les requêtes.

Ressources supplémentaires

• Introduction à l'API – Obtenez vos identifiants d'authentification et découvrez les bases

• Agent API - Comment utiliser un agent à partir d'une API

• Modèles disponibles - Sélectionnez le modèle LLM pour votre agent