ChatKit

ChatKit est la meilleure solution pour créer des interfaces de discussion avec des agents. Que vous développiez un assistant pour consulter une base de connaissances interne, accueillir de nouveaux collaborateurs, mener des recherches, faire des achats ou gérer un agenda, un bot de dépannage, un conseiller en planification financière ou un agent d’assistance, ChatKit fournit une interface de discussion personnalisable qui s’intègre à votre produit et prend en charge tous les détails de l’expérience utilisateur.

Utilisez les widgets d’interface intégrables, les prompts personnalisables, les appels d’outils, les pièces jointes et les visualisations du raisonnement détaillé (« chain-of-thought ») de ChatKit pour créer des agents sans avoir à réinventer l’interface de discussion.

Vue d’ensemble

Choisissez l’une des deux options d’intégration de ChatKit :

• Intégration sur votre propre serveur. Exécutez ChatKit sur votre infrastructure. Utilisez le SDK Python de ChatKit et connectez ChatKit au service d’agents de votre choix, y compris à un service créé avec le SDK Agents. Créez l’interface côté client à l’aide de widgets.
• Intégration existante hébergée dans Agent Builder. Si vous utilisez déjà ChatKit avec un workflow Agent Builder, vous pouvez continuer à utiliser ce workflow hébergé pendant la période de transition d’Agent Builder.

Premiers pas avec ChatKit

Intégration sur votre propre serveur

Utilisez le serveur de votre choix et les SDK de ChatKit pour créer une interface ChatKit adaptée à vos utilisateurs

Workflow hébergé existant

Connectez ChatKit à un workflow Agent Builder existant pendant la période de transition

Intégrez ChatKit à votre interface côté client

Utilisez cette option uniquement si votre intégration de ChatKit repose déjà sur un workflow Agent Builder. Pour créer une application ChatKit ou migrer avant l’arrêt d’Agent Builder, utilisez l’intégration avancée afin de connecter ChatKit à votre propre agent côté serveur.

La configuration de ChatKit avec un workflow hébergé existant se déroule en trois étapes. Ouvrez votre workflow existant tant qu’Agent Builder est disponible. Configurez ensuite ChatKit, puis ajoutez les fonctionnalités dont vous avez besoin pour votre interface de discussion.

1. Utilisez un workflow hébergé existant

Ouvrez votre workflow existant dans Agent Builder pour obtenir son identifiant. Pour préparer la transition, consultez le guide Migrer depuis Agent Builder.

L’interface de discussion intégrée à votre application se connectera au workflow que vous aurez sélectionné.

2. Configurez ChatKit dans votre produit

Pour configurer ChatKit, créez une session ChatKit et un point de terminaison sur votre serveur, transmettez l’identifiant de votre workflow, récupérez le secret client et transmettez-le au client ChatKit, puis ajoutez un script pour intégrer ChatKit à votre site.

Consigne de sécurité importante : lors de la création d’une session ChatKit, vous devez fournir le paramètre user avec une valeur propre à chaque utilisateur final. Votre serveur doit authentifier les utilisateurs de votre application et transmettre dans ce paramètre un identifiant unique pour chacun d’eux.

1. Générez un jeton client sur votre serveur.

   Cet exemple démarre un service qui crée une session ChatKit via l’API OpenAI et renvoie le secret client de la session :

   Python

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60# Replace the illustrative IDs and URLs below with your own resource values.
   import hmac
   import json
   import os
   from typing import Annotated
   
   import requests
   from fastapi import Depends, FastAPI, HTTPException
   from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
   from pydantic import BaseModel
   
   
   api_key = os.environ["OPENAI_API_KEY"]
   workflow_id = "wf_123"
   authenticated_users: dict[str, str] = json.loads(
       os.environ["CHATKIT_AUTHENTICATED_USERS"]
   )
   bearer_auth = HTTPBearer(auto_error=False)
   
   
   def get_authenticated_user_id(
       credentials: Annotated[
           HTTPAuthorizationCredentials | None,
           Depends(bearer_auth),
       ],
   ) -> str:
       if credentials is not None:
           for token, user_id in authenticated_users.items():
               if hmac.compare_digest(credentials.credentials, token):
                   return user_id
       raise HTTPException(status_code=401, detail="Invalid authentication token")
   
   
   class ChatKitSession(BaseModel):
       client_secret: str
   
   
   app = FastAPI()
   
   
   @app.post("/api/chatkit/session")
   def create_chatkit_session(
       user_id: Annotated[str, Depends(get_authenticated_user_id)],
   ):
       response = requests.post(
           "https://api.openai.com/v1/chatkit/sessions",
           headers={
               "Authorization": f"Bearer {api_key}",
               "Content-Type": "application/json",
               "OpenAI-Beta": "chatkit_beta=v1",
           },
           json={
               "workflow": {"id": workflow_id},
               "user": user_id,
           },
           timeout=30,
       )
       response.raise_for_status()
       session = ChatKitSession.model_validate(response.json())
       return {"client_secret": session.client_secret}

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57# Replace the illustrative IDs and URLs below with your own resource values.
   require "json"
   require "net/http"
   require "openssl"
   require "webrick"
   
   api_key = ENV.fetch("OPENAI_API_KEY")
   workflow_id = "wf_123"
   # Demo authentication mapping. Replace this with your application's session authentication.
   authenticated_users = JSON.parse(ENV.fetch("CHATKIT_AUTHENTICATED_USERS"))
   server = WEBrick::HTTPServer.new(
     BindAddress: "127.0.0.1", Port: Integer(ENV.fetch("PORT", "8000")),
     AccessLog: [], Logger: WEBrick::Log.new($stderr, WEBrick::BasicLog::WARN)
   )
   server.mount_proc("/api/chatkit/session") do |request, response|
     response["Content-Type"] = "application/json"
     response["Cache-Control"] = "no-store"
     unless request.path == "/api/chatkit/session" && request.request_method == "POST"
       response.status = 405
       response.body = JSON.generate(error: "Use POST /api/chatkit/session")
       next
     end
     token = request["Authorization"].to_s.delete_prefix("Bearer ")
     user = authenticated_users.find do |credential, _id|
       request["Authorization"].to_s.start_with?("Bearer ") &&
         OpenSSL.secure_compare(credential, token)
     end
     unless user
       response.status = 401
       response.body = JSON.generate(error: "Invalid authentication token")
       next
     end
     uri = URI("https://api.openai.com/v1/chatkit/sessions")
     upstream = Net::HTTP::Post.new(uri)
     upstream["Authorization"] = "Bearer #{api_key}"
     upstream["Content-Type"] = "application/json"
     upstream["OpenAI-Beta"] = "chatkit_beta=v1"
     upstream.body = JSON.generate(workflow: { id: workflow_id }, user: user.fetch(1))
     begin
       result = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 30) do |http|
         http.request(upstream)
       end
       result.value
       secret = JSON.parse(result.body).fetch("client_secret")
       raise "Missing session secret" unless secret.is_a?(String) && !secret.empty?
   
       response.body = JSON.generate(client_secret: secret)
     rescue
       response.status = 502
       response.body = JSON.generate(error: "Unable to create a ChatKit session")
     end
   end
   trap("INT") { server.shutdown }
   trap("TERM") { server.shutdown }
   puts("http://127.0.0.1:#{server.config[:Port]}/api/chatkit/session")
   $stdout.flush
   server.start

   Pour Ruby, installez WEBrick avec gem install webrick.

   Avant de démarrer le service, remplacez wf_123 par l’identifiant de votre workflow et définissez OPENAI_API_KEY et CHATKIT_AUTHENTICATED_USERS. Cette dernière variable contient un objet JSON qui associe chaque jeton Bearer de votre application à un identifiant utilisateur stable. En production, remplacez cette table de correspondance stockée dans une variable d’environnement par le mécanisme d’authentification ou de recherche de session de votre application.

2. Dans votre code côté serveur, transmettez l’identifiant de votre workflow et votre clé secrète au point de terminaison de session.

   Le secret client permet à votre interface ChatKit d’ouvrir ou d’actualiser la session de discussion. Transmettez-le immédiatement à la bibliothèque cliente de ChatKit sans le stocker.

   Consultez le dépôt chatkit-js sur GitHub.

   Pour Go, exécutez go get github.com/openai/openai-go/v3@v3.70.0. Pour Java, ajoutez la dépendance Maven com.openai:openai-java:4.75.1.

   Créez un jeton de session ChatKit

   JavaScript

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33export default async function getChatKitSessionToken(deviceId) {
     const apiKey = process.env.OPENAI_API_KEY;
     if (!apiKey) {
       throw new Error("OPENAI_API_KEY is required");
     }
   
     const response = await fetch("https://api.openai.com/v1/chatkit/sessions", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
         "OpenAI-Beta": "chatkit_beta=v1",
         Authorization: `Bearer ${apiKey}`,
       },
       body: JSON.stringify({
         workflow: { id: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1" },
         user: deviceId,
       }),
     });
   
     if (!response.ok) {
       throw new Error(
         `Failed to create a ChatKit session: ${response.status} ${await response.text()}`
       );
     }
   
     const { client_secret } = await response.json();
   
     if (!client_secret) {
       throw new Error("ChatKit session response did not include client_secret");
     }
   
     return client_secret;
   }

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15// Call after authenticating the request. Pass the user's stable ID from your
   // server-side authentication context, never a client-supplied device ID.
   func getChatKitSessionToken(ctx context.Context, client openai.Client, authenticatedUserID string) (string, error) {
   	// Replace this illustrative workflow ID with your published workflow.
   	session, err := client.Beta.ChatKit.Sessions.New(ctx, openai.BetaChatKitSessionNewParams{
   		User: authenticatedUserID,
   		Workflow: openai.ChatSessionWorkflowParam{
   			ID: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1",
   		},
   	})
   	if err != nil {
   		return "", err
   	}
   	return session.ClientSecret, nil
   }

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23import com.openai.client.OpenAIClient;
   import com.openai.client.okhttp.OpenAIOkHttpClient;
   import com.openai.models.beta.chatkit.sessions.*;
   import com.openai.models.beta.chatkit.threads.ChatSessionWorkflowParam;
   
   // Call after authenticating the request. Pass the user's stable ID from your
   // server-side authentication context, never a client-supplied device ID.
   static String getChatKitSessionToken(OpenAIClient client, String authenticatedUserId) {
     // Replace this illustrative workflow ID with your published workflow.
     return client
         .beta()
         .chatkit()
         .sessions()
         .create(
             SessionCreateParams.builder()
                 .user(authenticatedUserId)
                 .workflow(
                     ChatSessionWorkflowParam.builder()
                         .id("wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1")
                         .build())
                 .build())
         .clientSecret();
   }

3. Dans le répertoire de votre projet, installez les liaisons React de ChatKit :

   npm install @openai/chatkit-react

4. Ajoutez le script JavaScript de ChatKit à votre page. Insérez cet extrait dans le <head> de votre page ou à l’endroit où vous chargez vos scripts. Le navigateur téléchargera et exécutera ChatKit.

   index.html

   1
   2
   3
   4<script
   src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
   async
   ></script>

5. Affichez ChatKit dans votre interface. Passez au composant React MyChat une fonction getAppAuthToken qui renvoie le jeton Bearer de l’utilisateur actuel. Si vous utilisez l’onglet JavaScript, assurez-vous que cette même fonction est accessible dans la portée de l’extrait de code. Ce code envoie le jeton à votre serveur, récupère le secret client et monte un widget de discussion en direct connecté à votre workflow.

   Votre code côté client

   react

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28const chatkit = document.getElementById("my-chat");
   if (
     !chatkit ||
     !("setOptions" in chatkit) ||
     typeof chatkit.setOptions !== "function"
   ) {
     throw new Error("ChatKit element not found.");
   }
   
   chatkit.setOptions({
     api: {
       async getClientSecret() {
         const appAuthToken = await getAppAuthToken();
         const res = await fetch("/api/chatkit/session", {
           method: "POST",
           headers: {
             Authorization: `Bearer ${appAuthToken}`,
             "Content-Type": "application/json",
           },
         });
         if (!res.ok) {
           throw new Error(`ChatKit session request failed: ${res.status}`);
         }
         const { client_secret } = await res.json();
         return client_secret;
       },
     },
   });

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26import { ChatKit, useChatKit } from '@openai/chatkit-react';
   
      export function MyChat({ getAppAuthToken }) {
        const { control } = useChatKit({
          api: {
            async getClientSecret(existing) {
              if (existing) {
                // implement session refresh
               }
   
              const appAuthToken = await getAppAuthToken();
              const res = await fetch('/api/chatkit/session', {
                method: 'POST',
                headers: {
                  'Authorization': 'Bearer ' + appAuthToken,
                  'Content-Type': 'application/json',
                },
              });
              const { client_secret } = await res.json();
              return client_secret;
            },
          },
        });
   
        return <ChatKit control={control} className="h-[600px] w-[320px]" />;
      }

3. Développez et affinez votre intégration

Consultez la documentation sur la personnalisation des thèmes, les widgets et les actions pour mieux comprendre le fonctionnement de ChatKit. Vous pouvez aussi explorer les ressources suivantes pour tester votre interface de discussion, affiner vos prompts et ajouter des widgets et des outils.

Développez votre intégration

Explorez l’interface de ChatKit

Découvrez des exemples fonctionnels

Étapes suivantes

Lorsque votre intégration de ChatKit vous convient, découvrez comment l’optimiser à l’aide d’évaluations. Pour créer une application ChatKit ou migrer une application ChatKit existante qui repose sur un workflow hébergé dans Agent Builder, consultez la documentation sur l’intégration avancée.