ChatKit

O ChatKit é a melhor maneira de criar experiências de chat com agentes de IA. Você pode criar um assistente para consultar uma base de conhecimento interna, ajudar o RH a integrar novos funcionários, apoiar pesquisas, orientar compras ou agendar compromissos. Também pode criar um bot para solucionar problemas, um consultor de planejamento financeiro ou um agente de suporte. Em todos esses casos, o ChatKit oferece um chat incorporável e personalizável que cuida de todos os detalhes da experiência do usuário.

Use os widgets de interface incorporáveis, os prompts personalizáveis, o suporte a chamadas de ferramentas, os anexos de arquivos e as visualizações da cadeia de pensamento do ChatKit para criar agentes sem precisar recriar a interface de chat.

Visão geral

Escolha uma das duas formas de integrar o ChatKit:

• Integração com servidor próprio. Execute o ChatKit na sua infraestrutura. Use o SDK do ChatKit para Python e conecte-se a qualquer serviço com agentes de IA, inclusive a um serviço criado com o SDK de Agentes. Use widgets para criar o frontend.
• Integração existente com hospedagem no Agent Builder. Se você já usa o ChatKit com um fluxo de trabalho do Agent Builder, pode continuar usando esse fluxo hospedado durante o período de transição do Agent Builder.

Primeiros passos com o ChatKit

Integração com servidor próprio

Use qualquer servidor e os SDKs do ChatKit para criar uma experiência de chat personalizada para seus usuários

Fluxo de trabalho hospedado existente

Conecte o ChatKit a um fluxo de trabalho existente do Agent Builder durante o período de transição

Incorpore o ChatKit ao seu frontend

Use essa opção somente se sua implementação do ChatKit já usa um fluxo de trabalho do Agent Builder. Para criar aplicativos com o ChatKit ou migrar antes do encerramento do Agent Builder, use a integração avançada para conectar o ChatKit à sua própria implementação de agente no servidor.

A configuração do ChatKit com um fluxo de trabalho hospedado existente tem três etapas. Abra o fluxo de trabalho enquanto o Agent Builder ainda estiver disponível. Em seguida, configure o ChatKit e adicione recursos ao seu chat.

1. Use um fluxo de trabalho hospedado existente

Abra seu fluxo de trabalho no Agent Builder para obter o ID do fluxo. Para planejar a transição, consulte Como migrar do Agent Builder.

O chat incorporado ao seu frontend usará o fluxo de trabalho que você selecionar.

2. Configure o ChatKit no seu produto

Para configurar o ChatKit, você vai criar uma sessão do ChatKit e um endpoint no servidor, informar o ID do fluxo de trabalho, repassar o segredo do cliente e adicionar um script para incorporar o ChatKit ao seu site.

Aviso importante de segurança: Ao criar uma sessão do ChatKit, você deve informar o parâmetro user, cujo valor deve ser exclusivo para cada usuário final. Seu servidor deve autenticar os usuários do aplicativo e fornecer nesse parâmetro um identificador exclusivo para cada um.

1. Gere um token de cliente no seu servidor.

   Este exemplo inicia um serviço que cria uma sessão do ChatKit pela API da OpenAI e retorna o segredo do cliente dessa sessão:

   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

   Se você usa Ruby, instale o WEBrick com gem install webrick.

   Antes de iniciar o serviço, substitua wf_123 pelo ID do seu fluxo de trabalho e defina OPENAI_API_KEY e CHATKIT_AUTHENTICATED_USERS. O valor da segunda variável é um mapa JSON que associa os tokens bearer do aplicativo a IDs de usuário estáveis. Em produção, substitua esse mapa definido na variável de ambiente pelo mecanismo de autenticação ou de consulta de sessões do seu aplicativo.

2. No código do servidor, envie o ID do fluxo de trabalho e sua chave secreta ao endpoint de sessão.

   O segredo do cliente é a credencial que o frontend do ChatKit usa para abrir ou renovar a sessão de chat. Não armazene esse segredo. Repasse-o imediatamente à biblioteca cliente do ChatKit.

   Consulte o repositório chatkit-js no GitHub.

   Se você usa Go, execute go get github.com/openai/openai-go/v3@v3.70.0. Se usa Java, adicione a dependência Maven com.openai:openai-java:4.75.1.

   Crie um token de sessão do 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. No diretório do projeto, instale o pacote de integração do ChatKit com React:

   npm install @openai/chatkit-react

4. Adicione o script JS do ChatKit à página. Insira este trecho no elemento <head> da página ou no local em que você carrega os scripts. O navegador vai baixar e executar o ChatKit.

   index.html

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

5. Renderize o ChatKit na sua interface. Passe ao componente React MyChat uma função getAppAuthToken que retorne o token bearer do usuário atual. Se você usar a aba JavaScript, disponibilize a mesma função no escopo do trecho de código. Esse código envia a credencial ao seu servidor, obtém o segredo do cliente e monta um widget de chat ativo, conectado ao seu fluxo de trabalho.

   Código do seu 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. Desenvolva e aprimore seu chat

Consulte a documentação sobre personalização de temas, widgets e ações para saber mais sobre o funcionamento do ChatKit. Você também pode explorar os recursos a seguir para testar seu chat, refinar os prompts e adicionar widgets e ferramentas.

Desenvolva sua implementação

Explore a interface do ChatKit

Veja exemplos em funcionamento

Próximos passos

Quando sua implementação do ChatKit estiver como você quer, aprenda a otimizá-la com avaliações. Para criar aplicativos com o ChatKit ou migrar um aplicativo existente que usa um fluxo de trabalho hospedado no Agent Builder, consulte a documentação da integração avançada.