Créer un agent IA 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, de son prompt système, 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 de :

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 obligatoires sur l'agent :

• Nom de l'agent (name)

• Description (description)

• Prompt système (systemPrompt)

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 les propriétés de votre agent. L'API nécessite uniquement trois champs obligatoires :

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

• description – Description 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

Tous les autres champs, tels que les messages multilingues et le choix du modèle, sont facultatifs.

Exemple de configuration minimale :

{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries and provides product information",
  "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."
}

É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",
  "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."
}

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 en cURL :

curl -X POST https://api.swiftask.fr/admin/agent/create \
  -H "Authorization: Bearer xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries and provides product information",
    "systemPrompt": "You are a helpful customer support specialist. Answer questions about our products with accuracy and professionalism.",
    "greetingMessage": "Hello! How can I help you today?",
    "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. Answer questions about our products with accuracy and professionalism.",
    "greetingMessage": "Hello! How can I help you today?",
    "greetingMessageFR": "Bonjour ! Comment puis-je vous aider aujourd'hui ?",
    "createdAt": "2026-04-20T08:11:03.356Z"
  }
}

Enregistrez l'id et le slug de l'agent pour vos futurs appels API. Le 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: systemPrompt"
  }
}

Champs API disponibles

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

Champs obligatoires

Champs facultatifs

Cas d'usage pratiques

Automatisation du service client

Créez un agent d'assistance avec 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 cas complexes aux équipes humaines.

{
  "name": "Support Bot",
  "description": "Answers customer questions about our product",
  "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?",
  "model": "gpt-4o",
  "temperature": 0.3,
  "enableMemorySession": true
}

Qualification des prospects

Créez un agent commercial chargé de qualifier les prospects par des questions ciblées et de collecter leurs coordonnées.

{
  "name": "Sales Qualification Bot",
  "description": "Qualifies sales leads and collects information",
  "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.",
  "model": "claude-sonnet-4-6",
  "temperature": 0.6,
  "questionStarter": [
    "Tell me about your company",
    "What is your budget range?",
    "When do you need this solution?"
  ]
}

Assistant d'analyse stratégique

Déployez des agents à fort raisonnement pour vos synthèses d'informations internes et vos rapports stratégiques.

{
  "name": "Strategic Analyst",
  "description": "Synthesizes market data and structures analytical reports",
  "systemPrompt": "You are an internal strategic analyst. Synthesize information accurately, identify edge cases, and highlight key recommendations.",
  "model": "claude-opus-4-6",
  "temperature": 0.3,
  "enableMemorySession": true,
  "departement": "Strategy"
}

Conseils & bonnes pratiques

• Détaillez vos prompts système : Définissez clairement les règles, le ton et les comportements attendus en cas d'information indisponible.

• Choisissez le bon modèle : Utilisez des modèles rapides comme gpt-4o ou gemini-3.1-pro pour les flux de support client fréquents, et des modèles avancés comme claude-opus-4-6 pour l'analyse approfondie.

• Conservez les slugs d'agents : Enregistrez le slug généré pour réutiliser l'agent dans vos workflows, conversations de chat ou automatisations.

Dépannage

Erreur : « Missing required field: systemPrompt »

Cause : Un des champs obligatoires (name, description ou systemPrompt) est absent du corps de votre requête.

Solution : Vérifiez que ces trois propriétés obligatoires sont bien présentes avec des valeurs de type chaîne valides.

Erreur : « Invalid authorization token »

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

Solution :

1. Vérifiez que vous avez créé la clé API depuis Paramètres du compte > API

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

3. Vérifiez que la clé a été copiée sans espaces superflus

Erreur : « Missing header: 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 vos 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