API Agent

Appelez les agents Swiftask directement depuis votre application via l'API. Apprenez comment vous authentifier avec un jeton d'agent, envoyer des requêtes et recevoir des réponses.

Aperçus

nvoquez les agents Swiftask depuis vos propres applications. Au lieu de construire vous-même une logique IA complexe, exploitez des agents préconfigurés avec leurs propres bases de connaissances, compétences et instructions via une simple API REST.

Chaque agent possède son propre jeton d'authentification et un slug unique. Une fois authentifié, vous pouvez envoyer des requêtes à l'agent et recevoir des réponses intelligentes alimentées par la configuration de l'agent, sa base de connaissances et ses compétences connectées.

Prérequis

Avant d'appeler un agent via l'API, assurez-vous d'avoir :

• Jeton d'authentification de l'agent — Obtenu depuis la section Développeur de votre agent

• Slug de l'agent — L'identifiant unique de votre agent

• Connaissances HTTP de base — Compréhension des requêtes API REST et JSON

Obtenir votre jeton d'agent et votre slug

1. Connectez-vous à votre espace de travail Swiftask

2. Accédez à la section Agents

3. Sélectionnez l'agent que vous souhaitez appeler

4. Cliquez sur l'icône stylo (éditer) pour ouvrir les paramètres de l'agent

5. Accédez à la section Développeur

6. Copiez votre Jeton client et le Slug de l'agent

Gardez votre jeton client sécurisé — toute personne ayant accès à celui-ci peut faire des requêtes API au nom de votre agent et consommer vos crédits.

Guide étape par étape

Étape 1 : S'authentifier auprès de l'agent

Envoyez une requête REST pour obtenir un jeton d'accès pour l'agent.

const authenticate = async (clientToken) => {
  const clientUuid = crypto.randomUUID(); // Générer un ID unique pour cette session
  
  const response = await fetch(
    'https://graphql.swiftask.ai/public/widget-bot/' + clientToken,
    {
      method: 'GET',
      headers: {
        'x-client-uuid': clientUuid,
        'Content-Type': 'application/json',
      },
    }
  );

  if (!response.ok) {
    throw new Error('Authentification échouée');
  }

  const data = await response.json();
  return {
    accessToken: data.data.accessToken,
    botSlug: data.data.botSlug,
    todoId: data.data.todoId,
    starterSessionId: data.data.starterSessionId,
  };
};

// Utilisation
const auth = await authenticate('votre-jeton-client-agent');
console.log('Authentifié ! Jeton d\'accès :', auth.accessToken);

Étape 2 : Envoyer une requête à l'agent

Utilisez le jeton d'accès pour envoyer un message à l'agent et obtenir une réponse.

const sendRequest = async (accessToken, sessionId, message) => {
  const response = await fetch(
    'https://graphql.swiftask.ai/graphql',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + accessToken,
      },
      body: JSON.stringify({
        query: `
          mutation SendNewMessage($newMessageData: NewMessageInput!) {
            sendNewMessage(newMessageData: $newMessageData) {
              id
              message
              createdAt
            }
          }
        `,
        variables: {
          newMessageData: {
            message: message,
            sessionId: sessionId,
            isForAiReply: true,
          },
        },
      }),
    }
  );

  const result = await response.json();
  return result.data.sendNewMessage;
};

// Utilisation
const message = await sendRequest(auth.accessToken, auth.starterSessionId, 'Bonjour, agent !');
console.log('Message envoyé :', message.id);

Étape 3 : Obtenir la réponse de l'agent

Écoutez la réponse de l'agent en temps réel.

const subscribeToResponse = (accessToken, sessionId, onChunk, onComplete) => {
  const ws = new WebSocket('wss://graphql.swiftask.ai/graphql', ['graphql-ws']);
  
  let fullMessage = '';

  ws.addEventListener('open', () => {
    ws.send(JSON.stringify({
      type: 'connection_init',
      payload: {
        authorization: 'Bearer ' + accessToken,
      },
    }));

    // S'abonner au flux de messages
    ws.send(JSON.stringify({
      id: '1',
      type: 'start',
      payload: {
        query: `
          subscription OnMessageStream($sessionId: Float!) {
            onMessageStream(sessionId: $sessionId) {
              messageChunk
              botResponseMessageId
              isStoppable
            }
          }
        `,
        variables: { sessionId: sessionId },
      },
    }));
  });

  ws.addEventListener('message', (event) => {
    const message = JSON.parse(event.data);
    
    if (message.type === 'data' && message.payload.data.onMessageStream) {
      const chunk = message.payload.data.onMessageStream.messageChunk;
      fullMessage += chunk;
      onChunk(fullMessage);
    }
  });

  ws.addEventListener('close', () => {
    onComplete(fullMessage);
  });

  return ws;
};

// Utilisation
subscribeToResponse(
  auth.accessToken,
  auth.starterSessionId,
  (fullMessage) => {
    console.log('Réponse jusqu\'à présent :', fullMessage);
  },
  (finalMessage) => {
    console.log('Réponse finale :', finalMessage);
  }
);

Opérations principales

Envoyer un message à l'agent

Envoyez un message et déclenchez la réponse de l'agent.

Point de terminaison : POST https://graphql.swiftask.ai/graphql

En-têtes :

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

Mutation GraphQL :

mutation SendNewMessage($newMessageData: NewMessageInput!) {
  sendNewMessage(newMessageData: $newMessageData) {
    id
    message
    createdAt
    sessionId
    isBotReply
  }
}

Paramètres d'entrée :

Obtenir la réponse de l'agent (synchrone)

Pour les requêtes simples où vous n'avez pas besoin de streaming, obtenez la réponse complète immédiatement.

const callAgentSync = async (accessToken, sessionId, userMessage) => {
  const response = await fetch('https://graphql.swiftask.ai/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      query: `
        mutation SyncBotRequest($newMessageData: NewMessageInput!) {
          syncBotRequest(newMessageData: $newMessageData) {
            text
            isBotError
            sessionId
            sources
          }
        }
      `,
      variables: {
        newMessageData: {
          message: userMessage,
          sessionId: sessionId,
        },
      },
    }),
  });

  const result = await response.json();
  if (result.errors) {
    throw new Error(result.errors[0].message);
  }
  return result.data.syncBotRequest;
};

// Utilisation
const response = await callAgentSync(
  auth.accessToken,
  auth.starterSessionId,
  'Quel est votre tarif ?'
);
console.log('Réponse de l\'agent :', response.text);
console.log('Erreur ?', response.isBotError);
console.log('Sources utilisées :', response.sources);

Cas d'utilisation pratiques

Chatbot de support client

Intégrez votre agent de support Swiftask dans votre site web pour répondre aux questions des clients.

const handleUserQuestion = async (userQuestion) => {
  try {
    const auth = await authenticate('votre-jeton-agent-support');
    const response = await callAgentSync(
      auth.accessToken,
      auth.starterSessionId,
      userQuestion
    );

    if (response.isBotError) {
      return 'Désolé, j\'ai rencontré une erreur. Veuillez réessayer.';
    }
    return response.text;
  } catch (error) {
    console.error('Erreur lors de l\'appel à l\'agent :', error);
    return 'Impossible d\'atteindre l\'agent de support.';
  }
};

Service d'analyse de documents

Envoyez des documents à votre agent pour analyse et obtenez des réponses structurées.

const analyzeDocument = async (accessToken, sessionId, documentContent) => {
  const message = `Veuillez analyser ce document :\n\n${documentContent}`;
  const response = await callAgentSync(accessToken, sessionId, message);

  return {
    analysis: response.text,
    sources: response.sources,
    success: !response.isBotError,
  };
};

Conseils et bonnes pratiques

Mettre en cache votre jeton d'authentification

let cachedAuth = null;

const getAuth = async (clientToken) => {
  if (!cachedAuth) {
    cachedAuth = await authenticate(clientToken);
  }
  return cachedAuth;
};

Gérer les erreurs correctement

try {
  const response = await callAgentSync(accessToken, sessionId, message);
  
  if (response.isBotError) {
    console.error('Erreur de l\'agent :', response.text);
  } else {
    displayResponse(response.text);
  }
} catch (error) {
  console.error('Erreur réseau :', error);
}

Valider votre entrée

const validateMessage = (message) => {
  if (!message || message.trim().length === 0) {
    throw new Error('Le message ne peut pas être vide');
  }
  if (message.length > 5000) {
    throw new Error('Le message dépasse la limite de 5000 caractères');
  }
  return message.trim();
};

Prêt à appeler votre premier agent ? Utilisez le guide étape par étape ci-dessus pour vous authentifier et envoyer votre première requête à votre agent.