ChatKit

ChatKit은 에이전트 기반 채팅을 구축하는 데 가장 적합한 도구입니다. 사내 지식 베이스를 활용하는 어시스턴트부터 신입 직원 온보딩 도우미, 연구 파트너, 쇼핑 또는 일정 관리 어시스턴트, 문제 해결 봇, 재무 설계 상담사, 고객 지원 에이전트까지 다양한 용도로 사용할 수 있습니다. ChatKit은 채팅에 필요한 사용자 경험 전반을 처리하는 UI를 제공하며, 이를 서비스에 맞게 설정해 삽입할 수 있습니다.

ChatKit의 임베드형 UI 위젯, 맞춤 설정 가능한 프롬프트, 도구 호출 지원, 파일 첨부, 추론 과정 시각화를 활용하면 채팅 UI를 처음부터 구현할 필요 없이 에이전트를 만들 수 있습니다.

개요

ChatKit을 통합하는 방법은 두 가지입니다.

• 자체 서버 통합. 자체 인프라에서 ChatKit을 실행하세요. ChatKit Python SDK를 사용하면 Agents SDK로 구축한 서비스를 비롯해 어떤 에이전트 기반 서비스에도 연결할 수 있습니다. 프런트엔드는 위젯으로 구성하세요.
• Agent Builder에서 호스팅하는 기존 워크플로우와 통합. 이미 Agent Builder 워크플로우와 함께 ChatKit을 사용하고 있다면 Agent Builder 전환 기간에도 해당 워크플로우를 계속 사용할 수 있습니다.

ChatKit 시작하기

자체 서버 통합

원하는 서버와 ChatKit SDK를 사용해 서비스에 맞는 ChatKit 환경을 구축하세요

기존 호스팅 워크플로우

전환 기간 동안 ChatKit을 기존 Agent Builder 워크플로우에 연결하세요

프런트엔드에 ChatKit 삽입하기

이미 ChatKit의 백엔드로 Agent Builder 워크플로우를 사용하고 있는 경우에만 이 방법을 사용하세요. 새 ChatKit 앱을 만들거나 Agent Builder 서비스 종료 전에 기존 앱을 마이그레이션할 때는 고급 통합을 사용해 ChatKit을 자체 서버에서 구현한 에이전트에 연결하세요.

기존 호스팅 워크플로우에 ChatKit을 연결하는 과정은 크게 세 단계로 나뉩니다. 먼저 Agent Builder를 사용할 수 있는 동안 기존 워크플로우를 여세요. 그런 다음 ChatKit을 설정하고 기능을 추가해 원하는 채팅 환경을 구축하세요.

1. 기존 호스팅 워크플로우 사용하기

기존 워크플로우를 Agent Builder에서 열면 워크플로우 ID를 확인할 수 있습니다. 전환을 계획할 때는 Agent Builder에서 마이그레이션하기를 참고하세요.

프런트엔드에 삽입한 채팅은 선택한 워크플로우에 연결됩니다.

2. 제품에 ChatKit 설정하기

ChatKit을 설정하려면 ChatKit 세션과 서버 엔드포인트를 만들고 워크플로우 ID를 전달해 클라이언트 시크릿을 주고받습니다. 그런 다음 스크립트를 추가해 사이트에 ChatKit을 삽입합니다.

중요한 보안 유의 사항: ChatKit 세션을 만들 때는 반드시 user 매개변수를 전달해야 하며, 그 값은 최종 사용자마다 고유해야 합니다. 서버에서 애플리케이션 사용자를 인증한 뒤 해당 사용자의 고유 식별자를 이 매개변수로 전달해야 합니다.

1. 서버에서 클라이언트 토큰을 생성하세요.

   다음 예제는 OpenAI API를 통해 ChatKit 세션을 만들고 해당 세션의 클라이언트 시크릿을 반환하는 서비스를 시작합니다.

   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

   Ruby를 사용하는 경우 gem install webrick으로 WEBrick을 설치하세요.

   서비스를 시작하기 전에 wf_123을 자신의 워크플로우 ID로 바꾸고 OPENAI_API_KEY와 CHATKIT_AUTHENTICATED_USERS를 설정하세요. 두 번째 환경 변수에는 애플리케이션의 Bearer 토큰을 변하지 않는 사용자 ID에 매핑하는 JSON 객체를 지정합니다. 프로덕션 환경에서는 이 환경 변수의 매핑 대신 애플리케이션의 사용자 인증 또는 세션 조회 로직을 사용하세요.

2. 서버 측 코드에서 워크플로우 ID와 비밀 키를 세션 엔드포인트에 전달하세요.

   클라이언트 시크릿은 ChatKit 프런트엔드가 채팅 세션을 열거나 갱신할 때 사용하는 인증 정보입니다. 저장하지 말고 즉시 ChatKit 클라이언트 라이브러리에 전달하세요.

   GitHub의 chatkit-js 레포지토리를 참고하세요.

   Go를 사용하는 경우 go get github.com/openai/openai-go/v3@v3.70.0을 실행하세요. Java를 사용하는 경우 Maven 종속성 com.openai:openai-java:4.75.1을 추가하세요.

   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. 프로젝트 디렉터리에서 ChatKit React 바인딩을 설치하세요.

   npm install @openai/chatkit-react

4. 페이지에 ChatKit JS 스크립트를 추가하세요. 페이지의 <head> 또는 스크립트를 로드하는 위치에 다음 코드 조각을 삽입하면 브라우저가 ChatKit을 가져와 실행합니다.

   index.html

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

5. UI에 ChatKit을 렌더링하세요. React의 MyChat 컴포넌트에 현재 사용자의 Bearer 토큰을 반환하는 getAppAuthToken 함수를 전달하세요. JavaScript 탭의 예제를 사용한다면 해당 코드 조각의 스코프에서 같은 함수를 호출할 수 있도록 하세요. 이 코드는 인증 정보를 서버에 보내 클라이언트 시크릿을 받아온 다음, 워크플로우에 연결된 채팅 위젯을 마운트합니다.

   프런트엔드 코드

   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. 채팅 구현 및 개선하기

ChatKit의 작동 방식을 자세히 알아보려면 사용자 지정 테마, 위젯, 액션 문서를 참고하세요. 아래 자료를 활용해 채팅을 테스트하고 프롬프트를 다듬거나 위젯과 도구를 추가할 수도 있습니다.

ChatKit 구현하기

ChatKit UI 살펴보기

실행 가능한 예제 살펴보기

다음 단계

원하는 대로 ChatKit을 구현했다면 평가를 활용해 최적화하는 방법을 알아보세요. 새 ChatKit 앱을 만들거나 기존 ChatKit 앱을 Agent Builder 호스팅 워크플로우에서 자체 서버로 이전하려면 고급 통합 문서를 참고하세요.