ChatKit

ChatKit es la mejor forma de crear experiencias de chat con agentes. Ya sea que desarrolles un asistente para consultar una base de conocimientos interna, incorporar personal, investigar, hacer compras o programar citas, un bot para resolver problemas, un asesor de planificación financiera o un agente de soporte, ChatKit te ofrece un chat personalizable que puedes integrar en tu aplicación y que se encarga de todos los detalles de la experiencia de usuario.

Usa los widgets de interfaz integrables de ChatKit, los prompts personalizables, las llamadas a herramientas, los archivos adjuntos y las visualizaciones de la cadena de pensamiento para crear agentes sin tener que diseñar la interfaz de chat desde cero.

Descripción general

Elige una de las dos opciones de integración de ChatKit:

• Integración con un servidor propio. Ejecuta ChatKit en tu propia infraestructura. Usa el SDK de ChatKit para Python y conéctate a cualquier servicio de agentes, incluidos los que se crean con el SDK de Agentes. Usa widgets para crear el frontend.
• Integración existente alojada en Agent Builder. Si ya usas ChatKit con un flujo de trabajo de Agent Builder, puedes seguir usando ese flujo alojado durante el período de transición de Agent Builder.

Primeros pasos con ChatKit

Integración con un servidor propio

Usa cualquier servidor y los SDK de ChatKit para crear una experiencia de usuario a medida con ChatKit

Flujo de trabajo ya alojado

Conecta ChatKit a un flujo de trabajo existente de Agent Builder durante el período de transición

Integra ChatKit en tu frontend

Usa esta opción solo si tu implementación de ChatKit ya utiliza un flujo de trabajo de Agent Builder. Si creas una aplicación nueva con ChatKit o migras una existente antes del cierre de Agent Builder, usa la integración avanzada para conectar ChatKit a tu propia implementación de agentes en el servidor.

La configuración de ChatKit con un flujo de trabajo ya alojado consta de tres pasos. Abre tu flujo de trabajo mientras Agent Builder siga disponible. Luego configura ChatKit y agrega funciones para crear tu experiencia de chat.

1. Usa un flujo de trabajo ya alojado

Abre tu flujo de trabajo existente en Agent Builder. Obtendrás el ID del flujo de trabajo. Para planificar la transición, consulta la guía para migrar desde Agent Builder.

El chat integrado en tu frontend se conectará al flujo de trabajo que selecciones.

2. Configura ChatKit en tu producto

Para configurar ChatKit, crearás una sesión de ChatKit y un punto de acceso en el servidor, pasarás el ID de tu flujo de trabajo, intercambiarás el secreto de cliente y agregarás un script para integrar ChatKit en tu sitio.

Nota importante sobre seguridad: al crear una sesión de ChatKit, debes pasar el parámetro user con un valor único para cada usuario final. Tu servidor debe autenticar a los usuarios de tu aplicación y pasar en este parámetro un identificador único para cada uno.

1. Genera un token de cliente en tu servidor.

   Este ejemplo inicia un servicio que crea una sesión de ChatKit mediante la API de OpenAI y devuelve el secreto de cliente de la sesión:

   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

   Para Ruby, instala WEBrick con gem install webrick.

   Antes de iniciar el servicio, reemplaza wf_123 por el ID de tu flujo de trabajo y configura OPENAI_API_KEY y CHATKIT_AUTHENTICATED_USERS. El valor de esta última variable es un mapa JSON que asocia los tokens de portador de tu aplicación con identificadores de usuario estables. En producción, reemplaza este mapa definido en una variable de entorno por el mecanismo de autenticación o de consulta de sesiones de tu aplicación.

2. En el código del servidor, pasa el ID de tu flujo de trabajo y tu clave secreta al punto de acceso de sesiones.

   El secreto de cliente es la credencial que usa tu frontend de ChatKit para abrir o renovar la sesión de chat. Pásalo de inmediato a la biblioteca cliente de ChatKit sin almacenarlo.

   Consulta el repositorio de chatkit-js en GitHub.

   Para Go, ejecuta go get github.com/openai/openai-go/v3@v3.70.0. Para Java, agrega la dependencia de Maven com.openai:openai-java:4.75.1.

   Crea un token de sesión de 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. En el directorio de tu proyecto, instala los bindings de ChatKit para React:

   npm install @openai/chatkit-react

4. Agrega el script JS de ChatKit a tu página. Coloca este fragmento en el <head> de la página o donde cargues los scripts. El navegador descargará y ejecutará ChatKit.

   index.html

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

5. Muestra ChatKit en tu interfaz. Pasa al componente MyChat de React una función getAppAuthToken que devuelva el token de portador del usuario actual. Si usas la pestaña de JavaScript, asegúrate de que esa misma función esté disponible en el ámbito del fragmento de código. Este código envía la credencial a tu servidor, obtiene el secreto de cliente y monta un widget de chat en vivo conectado a tu flujo de trabajo.

   Código de tu frontend

   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. Desarrolla y perfecciona tu chat

Consulta la documentación sobre temas personalizados, widgets y acciones para saber más sobre el funcionamiento de ChatKit. También puedes explorar los siguientes recursos para probar tu chat, ajustar los prompts y agregar widgets y herramientas.

Desarrolla tu implementación

Explora la interfaz de ChatKit

Consulta ejemplos funcionales

Próximos pasos

Cuando estés conforme con tu implementación de ChatKit, aprende a optimizarla con evaluaciones. Si vas a crear una aplicación con ChatKit o a migrar una aplicación de ChatKit existente para que deje de usar un flujo de trabajo alojado en Agent Builder, consulta la documentación de la integración avanzada.