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

Présentation

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 particulier n'est nécessaire. Il vous suffit de pointer le SDK vers le point de terminaison de l'API Swiftask, de vous authentifier à l'aide de votre clé API Swiftask et de spécifier le slug de votre agent comme nom de modèle. Le SDK se charge du reste.

Cette fonctionnalité 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 devez disposer :

• Un compte Swiftask sur lequel au moins un agent a été créé.

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

• Le « slug » de votre agent : un identifiant unique que vous trouverez 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.

Configuration

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

Authentification : clé API Swiftask (disponible dans Paramètres du compte → API)

Paramètre du modèle : le slug de votre agent (disponible dans les paramètres de l'agent → onglet API)

Configuration étape par étape

1. Récupérez votre 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. Trouvez 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. Installez le SDK OpenAI

Choisissez votre langage et installez le SDK :

Python :

pip install openai 

JavaScript / Node.js :

npm install openai 

4. Configurez le SDK et effectuez une requête de base

Utilisez votre clé API et votre slug d'agent pour configurer le client. Voici quelques 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);

Paramètres clés

Appel de fonctions/outils

Swiftask prend en charge trois méthodes pour définir des outils pour votre agent. Elles fonctionnent par ordre de priorité :

Méthode 1 : externalTools (spécifique à Swiftask, priorité maximale)

Utilisez le champ « externalTools » avec les définitions JSON Schema. C'est l'approche recommandée si vous souhaitez éviter les conflits avec d'autres utilisations du champ standard « tools ».

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[
        {"role": "user", "content": "What is the weather in Paris?"}
    ],
    extra_body={
        "externalTools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ]
    }
    
)

Méthode 2 : tools (format OpenAI standard)

Utilisez le champ standard OpenAI « tools » si « externalTools » n’est pas fourni. Le format est identique à la spécification d’appel de fonction d’OpenAI.

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[
        {"role": "user", "content": "What is the weather in Paris?"}
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"},
                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    tool_choice="auto"
)

Méthode 3 : invite système XML (mode de secours)

Si ni tools ni externalTools ne sont fournis, le backend tente d’analyser les définitions d’outils à partir de votre invite système en utilisant un format XML strict. Il s’agit d’une solution de secours « au mieux », principalement destinée à assurer la compatibilité avec Cline et des outils similaires.

Format attendu :

## tool_name
Description: Description of what this tool does.
Parameters:
- param1: (required) Description of param1.
- param2: (optional) Description of param2.
Usage:
<tool_name>
<param1>value</param1>
<param2>value</param2>
</tool_name>

Remarques importantes :

• La ligne contenant le nom de l'outil doit correspondre à l'expression régulière suivante : ^##\s+([a-zA-Z0-9_-]+)\s*$

• Doit inclure les libellés littéraux « Description: » et « Parameters: »

• Les types de paramètres sont détectés automatiquement : booléen si le nom contient « boolean » ou est « recursive »/« requires_approval » ; entier s’il contient « integer » ou est « timeout » ; objet s’il contient « json object » ; sinon, chaîne de caractères.

• Ce mode n’est pas garanti ; un format légèrement différent ne sera pas analysé.

Paramètre de choix de l’outil

Contrôlez quand et comment les outils sont invoqués :

# Auto mode: model decides if a tool is needed
tool_choice="auto"

# None mode: model never calls tools
tool_choice="none"

# Force specific tool
tool_choice={
    "type": "function",
    "function": {"name": "get_current_weather"}
}

Format de réponse : non-streaming

Lorsque le modèle décide d’appeler un outil, la réponse inclut tool_calls et finish_reason: "tool_calls" :

{
  "id": "chatcmpl-xxxxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "mon-agent-slug",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_current_weather",
              "arguments": "{\"location\":\"Paris\",\"unit\":\"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 50,
    "total_tokens": 200
  }
}

Détails clés :

• Le contenu est généralement nul lorsque des tool_calls sont présents, mais il peut contenir un texte d'accompagnement provenant du modèle.

• finish_reason est « "tool_calls" » (et non « "stop" »)

• arguments est une chaîne JSON complète, non fragmentée

Format de réponse : Streaming

En mode streaming (stream=True), le backend envoie des Server-Sent Events (SSE). Les arguments d’appel de l’outil sont envoyés dans leur intégralité en un seul bloc, et non token par token comme chez OpenAI.

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[...],
    tools=[...],
    stream=True
)

for chunk in response:
    if chunk.choices[0].delta.tool_calls:
        print(chunk.choices[0].delta.tool_calls[0].function.arguments)

Structure du flux :

1. Delta initial avec role: "assistant"

2. Deltas de contenu (si du texte est généré avant les appels d’outils)

3. Deltas d’appel d’outil avec les arguments complets dans un seul bloc

4. Delta final avec l’finish_reason: "tool_calls"

5. Bloc d’utilisation facultatif en cas de stream_options.include_usage: true

6. data: [DONE]

Exemple complet de cycle aller-retour d’appel d’outil

Voici un exemple complet illustrant le cycle complet : requête → réponse à l’appel d’outil → résultat de l’outil → requête suivante.

from openai import OpenAI

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

# Step 1: Initial request with tool definitions
response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[
        {"role": "user", "content": "What is the weather in Paris?"}
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get current weather",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {"type": "string"}
                    },
                    "required": ["location"]
                }
            }
        }
    ]
)

# Step 2: Check if tool was called
if response.choices[0].finish_reason == "tool_calls":
    tool_call = response.choices[0].message.tool_calls[0]
    tool_name = tool_call.function.name
    tool_args = tool_call.function.arguments
    
    # Step 3: Execute the tool (simulated here)
    import json
    args = json.loads(tool_args)
    weather_result = f"Sunny, 18°C in {args['location']}"
    
    # Step 4: Send tool result back to the model
    response = client.chat.completions.create(
        model="AGENT_SLUG",
        messages=[
            {"role": "user", "content": "What is the weather in Paris?"},
            {
                "role": "assistant",
                "content": None,
                "tool_calls": [
                    {
                        "id": tool_call.id,
                        "type": "function",
                        "function": {
                            "name": tool_name,
                            "arguments": tool_args
                        }
                    }
                ]
            },
            {
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": weather_result
            }
        ],
        tools=[...]  # Must include tools again
    )
    
    # Step 5: Get final response
    print(response.choices[0].message.content)

Avec le streaming (en temps réel)

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 :

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[{"role": "user", "content": "Analyze this document"}],
    stream=True
)

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

JavaScript / TypeScript:

const response = await client.chat.completions.create({
    model: 'AGENT_SLUG',
    messages: [
        { role: 'user', content: 'Tell me a story.' }
    ],
    stream: true,});

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

Contenu multimodal

Les messages peuvent inclure du texte, des images et des fichiers :

response = client.chat.completions.create(
    model="AGENT_SLUG",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.jpg",
                        "detail": "auto"  # or "low", "high"
                    }
                }
            ]
        }
    ]
) 

Types de contenu pris en charge :

• text : texte brut

• image_url : URL (http/https ou URI de données Base64)

• file : fichier encodé en Base64 avec nom de fichier

Cas d'utilisation concrets

Cas n° 1 : Intégrer un agent dans un chatbot d’assistance

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

from openai import OpenAI

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

def answer_customer_question(question):
    response = await client.chat.completions.create(
        model="support_agent_slug",
        messages=[
            {"role": "user", "content": question}
        ]
    )
    return response.choices[0].message.content

Cas n° 2 : Traitement par lots de 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 = ["Doc 1 content...", "Doc 2 content..."]

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

Cas n° 3 : Utilisation de l'appel d'outil pour récupérer des données

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

# Agent calls a tool to retrieve customer data
response = client.chat.completions.create(
    model="sales_agent_slug",
    messages=[
        {"role": "user", "content": "Get details for customer ID 12345"}
    ],
    tools=[
        {
            "type": "function",
            "function": {
                "name": "get_customer_details",
                "description": "Retrieve customer information",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "customer_id": {"type": "string"}
                    },
                    "required": ["customer_id"]
                }
            }
        }
    ]
)

Gestion des erreurs

Toutes les erreurs respectent le format standard d'OpenAI :

{
  "error": {
    "message": "Invalid API Key",
    "type": "authentication_error",
    "param": null,
    "code": null
  }
}

Erreurs courantes :

Limitations

• Les appels d'outils parallèles dépendent de la capacité sous-jacente du modèle de votre agent ; la structure de réponse prend en charge plusieurs entrées tool_calls.

• Pas de n > 1 : un seul choix est toujours renvoyé, même si l'option « n » est spécifiée.

• Les outils doivent être renvoyés : le serveur ne mémorise pas les outils entre les requêtes ; incluez-les à chaque appel.

• L'analyse XML est effectuée au mieux : le mode d'analyse des invites système n'est pas garanti ; utilisez tools ou externalTools pour plus de fiabilité.

Conseils et bonnes pratiques

• Protégez vos clés API : ne les intégrez jamais dans un système de contrôle de version. Utilisez des variables d’environnement.

• Réincluez les outils dans chaque requête : même si vous poursuivez une conversation, envoyez toujours le tableau des outils.

• Utilisez « sessionId » pour le contexte : si vous poursuivez une session Swiftask, incluez « sessionId » pour conserver le contexte.

• Utilisez le streaming pour une meilleure expérience utilisateur : utilisez stream=True pour afficher les réponses en temps réel.

• Privilégiez externalTools ou tools : évitez de vous appuyer sur l’analyse syntaxique des invites système XML, sauf si vous effectuez une intégration avec Cline.

Ressources supplémentaires

• Comment envoyer des demandes aux agents Swiftask

• Accéder à AI et à Agent via l'API

• Créer un agent IA via l'API

• Utilisation des agents de Chat