ChatKit

ChatKit은 에이전트형 채팅(agentic chat) 경험을 만드는 가장 좋은 방법이에요. 내부 지식 베이스 어시스턴트, HR 온보딩 도우미, 연구 동반자, 쇼핑·일정 예약 어시스턴트, 트러블슈팅 봇, 재무 계획 어드바이저, 지원 에이전트 등 무엇을 만들든, ChatKit은 사용자 경험의 모든 세부 사항을 처리하는 커스터마이즈 가능한 채팅 embed를 제공해요.

ChatKit의 삽입형 UI 위젯, 커스터마이즈 가능한 프롬프트, 툴 호출 지원, 파일 첨부, chain-of-thought 시각화를 사용하면 채팅 UI를 새로 만들지 않고도 에이전트를 구축할 수 있어요.

출처: 문서

본문

개요 (Overview)

두 가지 ChatKit 경로 중에서 고를 수 있어요.

커스텀 서버 통합. 자체 인프라에서 ChatKit을 실행해요. ChatKit Python SDK를 사용하고, Agents SDK로 만든 것을 포함해 어떤 에이전트형 서비스에도 연결해요. 프론트엔드는 위젯으로 만들어요.
기존 Agent Builder 호스팅 통합. 이미 Agent Builder 워크플로우와 함께 ChatKit을 쓰고 있다면, Agent Builder 전환 기간 동안 그 호스팅 워크플로우를 계속 사용할 수 있어요.

OpenAI는 Agent Builder를 단계적으로 없애고 있어요. 기존 사용자는 전환 기간 동안 계속 쓸 수 있고, 제품은 2026년 11월 30일에 종료될 예정이에요. ChatKit은 계속 제공돼요. 새 작업이나 마이그레이션 계획에는 자체 서버 측 에이전트 구현과 함께 고급 ChatKit 통합을 사용하고, Agent Builder 전환 지침은 Agent Builder에서 마이그레이션 문서를 참고하세요.

ChatKit 시작하기

커스텀 서버 통합: 어떤 서버든 ChatKit SDK와 함께 사용해 나만의 커스텀 ChatKit 사용자 경험을 만들어요.
기존 호스팅 워크플로우: 전환 기간 동안 ChatKit을 기존 Agent Builder 워크플로우에 연결해요.

프론트엔드에 ChatKit 삽입하기

이 경로는 ChatKit 구현을 뒷받침하는 기존 Agent Builder 워크플로우가 있을 때만 써요. 새 ChatKit 앱이거나 Agent Builder 종료 전에 마이그레이션할 때는 고급 통합으로 자체 서버 측 에이전트 구현에 연결하세요.

높은 수준에서 기존 호스팅 워크플로우로 ChatKit을 설정하는 것은 3단계 과정이에요. Agent Builder가 여전히 사용 가능한 동안 기존 워크플로우를 열고, ChatKit을 설정하고 채팅 경험을 만들기 위해 기능을 추가하면 돼요.

OpenAI-hosted ChatKit

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

Agent Builder에서 기존 워크플로우를 열면 워크플로우 ID를 받아요. 전환 계획은 Agent Builder에서 마이그레이션 문서를 참고하세요.

프론트엔드에 삽입된 채팅이 선택한 워크플로우를 가리키게 돼요.

2. 제품에 ChatKit 설정하기

ChatKit을 설정하려면 ChatKit 세션과 서버 엔드포인트를 만들고, 워크플로우 ID를 전달하고, 클라이언트 시크릿을 교환하고, ChatKit을 사이트에 삽입하는 스크립트를 추가하면 돼요.

중요한 보안 참고: ChatKit 세션을 만들 때는 개별 최종 사용자마다 고유해야 하는 user 파라미터를 꼭 전달해야 해요. 서버가 애플리케이션의 사용자를 인증하고 이 파라미터에 고유 식별자를 전달해야 합니다.

서버에서 클라이언트 토큰을 생성해요.

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

# 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}

Ruby(WEBrick) 버전도 같은 구조예요. Ruby를 쓰려면 gem install webrick으로 설치하고, 서비스를 시작하기 전에 wf_123을 워크플로우 ID로 바꾸고 OPENAI_API_KEY와 CHATKIT_AUTHENTICATED_USERS를 설정하세요. 후자는 애플리케이션의 bearer 토큰을 안정적인 사용자 ID에 매핑하는 JSON 맵이에요. 프로덕션에서는 이 환경 변수 기반 맵을 애플리케이션의 인증이나 세션 조회로 바꾸세요.

서버 측 코드에서 세션 엔드포인트에 워크플로우 ID와 시크릿 키를 전달해요.

클라이언트 시크릿은 ChatKit 프론트엔드가 채팅 세션을 열거나 새로 고치는 데 쓰는 자격 증명이에요. 서버에 저장하지 않고 ChatKit 클라이언트 라이브러리에 즉시 넘겨주면 돼요.

chatkit-js repo를 참조하세요.

export 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;
}

프로젝트 디렉터리에서 ChatKit React 바인딩을 설치해요.

npm install @openai/chatkit-react

페이지에 ChatKit JS 스크립트를 추가해요. 페이지의 <head>나 스크립트를 로드하는 곳에 이 스니펫을 넣으면, 브라우저가 ChatKit을 가져와 실행해요.

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

UI에서 ChatKit을 렌더링해요. React MyChat 컴포넌트에 현재 사용자의 bearer 토큰을 반환하는 getAppAuthToken 함수를 전달해요. JavaScript 탭을 쓰면 스니펫의 스코프에 같은 함수를 만들어 두세요. 이 코드가 그 자격 증명을 서버로 보내 클라이언트 시크릿을 가져오고, 워크플로우에 연결된 라이브 채팅 위젯을 마운트해요.

const 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;
    },
  },
});

import { 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} />;
}

3. 만들고 반복하기 (Build and iterate)

커스텀 테마, 위젯, 액션 문서에서 ChatKit이 어떻게 동작하는지 더 알아보세요. 또는 아래 리소스를 탐색해 채팅을 테스트하고 프롬프트를 반복하며 위젯과 툴을 추가해 보세요.

구현 만들기

GitHub의 ChatKit 문서: 인증 처리, 테마·커스터마이징 추가 등을 배울 수 있어요.
ChatKit Python SDK: 서버 측 저장소, 접근 제어, 툴 등 백엔드 기능을 추가할 수 있어요.
ChatKit JS SDK: ChatKit JS repo를 살펴보세요.

ChatKit UI 탐색하기

chatkit.world: ChatKit의 인터랙티브 데모를 조작해 볼 수 있어요.
Widget builder: 사용 가능한 위젯을 둘러볼 수 있어요.
ChatKit playground: 인터랙티브 데모로 직접 배워볼 수 있어요.

동작 예시 보기

GitHub 샘플: ChatKit의 동작 예시를 보고 영감을 얻어요.
Starter 앱 repo: 완전히 동작하는 템플릿으로 시작할 수 있게 repo를 클론해요.

다음 단계

ChatKit 구현에 만족하면 evals로 최적화하는 법을 배워 보세요. 새 ChatKit 앱이거나 기존 ChatKit 앱을 Agent Builder 호스팅 워크플로우에서 옮기려면 고급 통합 문서를 참고하세요.

ChatKit

ChatKit

본문

개요 (Overview)

ChatKit 시작하기

프론트엔드에 ChatKit 삽입하기

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

2. 제품에 ChatKit 설정하기

3. 만들고 반복하기 (Build and iterate)

다음 단계

더 알아보기 (Learn more)