Accéder aux agents Swiftask via le SDK OpenAI (recommandée)

Écrit par Stanislas

Dernière mise à jour Il y a 13 jours

Vue d'ensemble

Les agents Swiftask sont compatibles avec le SDK OpenAI. Cela signifie que vous pouvez utiliser n'importe quelle bibliothèque cliente OpenAI (Python, JavaScript, Node.js ou autres) pour envoyer des messages à vos agents et recevoir des réponses, exactement comme vous le feriez avec les modèles GPT d'OpenAI.

Aucun code d'intégration spécial n'est nécessaire. Il vous suffit de pointer le SDK vers le point de terminaison API de Swiftask, de vous authentifier avec votre clé API Swiftask, et de spécifier le slug de votre agent comme nom du modèle. Le SDK gère le reste.

C'est utile lorsque vous souhaitez intégrer des agents Swiftask dans des applications, des scripts ou des workflows qui utilisent déjà le SDK OpenAI, ou lorsque vous préférez l'interface familière d'OpenAI.

Prérequis

Avant de pouvoir utiliser l'API, vous avez besoin de :

  • Un compte Swiftask avec au moins un agent créé.

  • Une clé API: générée à partir de vos paramètres de compte.

  • Le slug de votre agent: un identifiant unique trouvé dans les paramètres de votre agent.

  • Un SDK OpenAI installé dans votre projet (Python, JavaScript, etc.).

L'API fonctionne avec n'importe quel compte, tant que votre clé API est valide et non expirée.

Guide étape par étape

1. Créer une clé API

  1. Allez dans Paramètres du compte (cliquez sur l’ icône des paramètres en bas à gauche, puis sélectionnez Paramètres du compte).

  2. Accédez à la section API.

  3. Cliquez sur Créer une nouvelle clé.

  4. Entrez un nom pour votre clé (par exemple, « Accès Bot Production »).

  5. Définissez optionnellement une date d'expiration.

  6. Cliquez sur Créer.

  7. Copiez votre clé immédiatement — elle ne s'affichera qu'une seule fois. Stockez-la en sécurité (par exemple, dans un fichier .env).

2. Obtenir le slug de votre agent

  1. Ouvrez l'agent auquel vous souhaitez accéder.

  2. Cliquez sur l'icône Paramètres (icône d'engrenage) sur votre agent.

  3. Allez à l'onglet API.

  4. Copiez le texte dans la section Slug unique de l’agent. C'est l'identifiant unique que vous utiliserez comme paramètre model.

3. Installer le SDK OpenAI

Choisissez votre langage et installez le SDK :

Python :

pip install openai

JavaScript / Node.js :

npm install openai

4. Configurer le SDK et effectuer une requête

Utilisez votre clé API et le slug de votre agent pour configurer le client. Voici des exemples :

Python :

from openai import OpenAI

client = OpenAI(
    api_key="VOTRE_CLE_API",    
    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)

JavaScript / TypeScript :

import OpenAI from 'openai';

const client = new OpenAI({
    apiKey: 'VOTRE_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);

5. Utiliser le streaming (optionnel)

Si vous souhaitez recevoir les réponses en temps réel au fur et à mesure qu'elles sont générées, activez le streaming :

Python :

sstream = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[
        {"role": "user", "content": "Raconte-moi une histoire."}
    ],
    stream=True)
for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

JavaScript / TypeScript :

const stream = await client.chat.completions.create({
    model: 'AGENT_SLUG',
    messages: [
        { role: 'user', content: 'Raconte-moi une histoire.' }
    ],
    stream: true,});

for await (const chunk of stream) {
    if (chunk.choices[0].delta.content) {
        process.stdout.write(chunk.choices[0].delta.content);
    }
}

Cas d'usage pratiques

Cas 1 : Intégrer un agent dans un chatbot d'assistance client

Vous avez un agent d'assistance client dans Swiftask et souhaitez l'utiliser dans votre application d'assistance Node.js.

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

async function answerCustomerQuestion(question) {
    const response = await client.chat.completions.create({
        model: "AGENT_SLUG",
        messages: [
            { role: 'user', content: question }
        ]
    });
    return response.choices[0].message.content;
}

Cas 2 : Traiter par lots des documents avec un agent

Vous avez un agent d'analyse de documents et souhaitez traiter 100 documents dans un script Python.

from openai import OpenAI

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

documents = ["Contenu du Document 1 ", "Contenu du Document 2"]

for doc in documents:
    response = client.chat.completions.create(
        model="AGENT_SLUG",
        messages=[
            {"role": "user", "content": f"Analyser ceci: {doc}"}
        ]
    )
    print(response.choices[0].message.content)

Cas 3 : Diffuser les réponses en streaming dans une application web

Vous souhaitez afficher les réponses de l'agent en temps réel sur une page web.

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

async function streamAgentResponse(userMessage, onChunk) {
    const stream = await client.chat.completions.create({
        model: "AGENT_SLUG",
        messages: [{ role: 'user', content: userMessage }],
        stream: true,
    });

    for await (const chunk of stream) {
        if (chunk.choices[0].delta.content) {
            onChunk(chunk.choices[0].delta.content);
        }
    }}

onseils et bonnes pratiques

  • Sécurisez votre clé API — Traitez-la comme un mot de passe. Utilisez des variables d'environnement ou des outils de gestion des secrets, ne la codez jamais en dur.

  • 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é. Renouvelez les clés régulièrement.

  • Utilisez des noms de clé explicites — Nommez vos clés par cas d'usage (par exemple, « Bot Production », « Bot Test ») pour suivre l'utilisation.

  • Gérez les erreurs avec élégance — Encapsulez les appels API dans des blocs try-catch et fournissez des messages d'erreur significatifs aux utilisateurs.

  • Utilisez le streaming pour une meilleure expérience utilisateur — Les réponses en streaming semblent plus rapides aux utilisateurs finaux car ils voient le contenu apparaître en temps réel.

Dépannage

Erreur : 401 Unauthorized (Non autorisé)

  • Cause : Votre clé API est invalide ou manquante.

  • Correction : Vérifiez que votre clé API est correcte et incluse dans l'en-tête Authorization en tant que jeton Bearer. Vérifiez qu'elle n'a pas expiré dans vos paramètres de compte.

Erreur : 400 Bad Request (Mauvaise requête)

  • Cause : Le slug de l'agent est incorrect ou l'agent n'existe pas.

  • Correction : Vérifiez deux fois votre slug d'agent dans les paramètres de votre agent sous l'onglet API. Assurez-vous qu'il correspond exactement.

Pas de réponse ou délai d'attente dépassé

  • Cause : L'agent prend plus de temps que prévu pour répondre, ou il y a un problème de réseau.

  • Correction : Vérifiez votre connexion Internet. Si vous utilisez le streaming, assurez-vous que votre client supporte les événements envoyés par le serveur (SSE). Réessayez avec un message plus simple.

Le streaming s'arrête de manière inattendue

  • Cause : La connexion a été interrompue ou l'agent a terminé le traitement.

  • Correction : Assurez-vous que votre client gère correctement le marqueur DONE qui signale la fin du flux. Encapsulez la logique de streaming dans la gestion des erreurs.