ChatKit 是打造智慧體對話體驗的最佳方式。無論你要開發內部知識庫助理、協助新人到職的人資助理、研究夥伴、購物或排程助理、疑難排解機器人、財務規劃顧問或客服智慧體,ChatKit 都提供可自訂的嵌入式對話介面,替你處理使用者體驗的各項細節。
ChatKit 提供可嵌入的介面小工具和可自訂的提示詞,並支援工具呼叫、檔案附件和思路鏈視覺化,讓你建立智慧體時無須從頭開發對話介面。
概覽
ChatKit 有兩種整合方式:
- 整合自有伺服器。在自己的基礎架構上執行 ChatKit。使用 ChatKit Python SDK 連接任何智慧體服務,包括使用 Agents SDK 建立的服務,再以小工具建構前端。
- 沿用 Agent Builder 代管的工作流程。如果你已將 ChatKit 與 Agent Builder 工作流程整合,可以在 Agent Builder 過渡期間繼續使用該代管工作流程。
OpenAI 正逐步棄用 Agent Builder。現有使用者可在過渡期間繼續使用 Agent Builder,該產品預定於 2026 年 11 月 30 日停止服務。ChatKit 仍可使用。如果你要開發新專案或規劃遷移,請使用 ChatKit 進階整合連接你在伺服器端實作的智慧體,並參閱從 Agent Builder 遷移,瞭解過渡期間的做法。
開始使用 ChatKit
將 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 參數,而且每位終端使用者的參數值都應不同。伺服器必須驗證應用程式使用者的身分,並透過此參數傳入該使用者的唯一識別碼。
-
在伺服器上產生用戶端權杖。
下列範例會啟動一項服務,透過 OpenAI API 建立 ChatKit 工作階段,並傳回該工作階段的用戶端密鑰:
Python# 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,請執行
gem install webrick安裝 WEBrick。啟動服務前,請將
wf_123替換為你的工作流程 ID,並設定OPENAI_API_KEY和CHATKIT_AUTHENTICATED_USERS。後者的值是一份 JSON 對照表,將應用程式的 Bearer 權杖對應到固定的使用者 ID。在正式環境中,請改用應用程式的身分驗證或工作階段查詢機制,取代存放在環境變數中的對照表。 -
在伺服器端程式碼中,將工作流程 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 工作階段權杖TypeScriptexport default async function getChatKitSessionToken(deviceId: string) { 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。index.html<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js" async ></script> -
在使用者介面中呈現 ChatKit。請將一個函式傳給 React
MyChat元件,此函式名為getAppAuthToken,會傳回目前使用者的 Bearer 權杖。如果使用 TypeScript 分頁中的範例,請確保程式碼片段可在其作用域內存取同一個函式。這段程式碼會將憑證傳送到你的伺服器、取得用戶端密鑰,並掛載已連接到你所選工作流程的即時對話小工具。你的前端程式碼reactimport { 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 JS 程式碼庫。
探索 ChatKit 使用者介面
試用 ChatKit 的互動示範。
瀏覽可用的小工具。
透過互動示範動手練習。
查看可執行的範例
查看可執行的 ChatKit 範例,從中獲得靈感。
複製程式碼庫,即可從功能完整且可直接執行的範本開始開發。
後續步驟
當 ChatKit 實作符合你的需求後,可以進一步瞭解如何透過評估來最佳化實作。如果你要開發新的 ChatKit 應用程式,或將現有的 ChatKit 應用程式遷出 Agent Builder 代管的工作流程,請參閱進階整合文件。

