Разширена интеграция във вашето приложение
На тази страница
- Какво остава след демонстрацията
- Удостоверяване на всяка заявка
- Всеки потребител получава собствените си разговори
- предоставете на модела контекста на Вашето приложение
- Клиентски инструменти
- Управлявайте ChatKit от Вашето приложение
- Наблюдавайте какво се случва
- Преди да преминете към продукция
- Ключови изводи
Урокът е пренаписан на 3 ноември 2026 г. Предишната версия разчиташе на измислени свойства и събития (
ChatProvider, режим „странична лента“, запазване чрез потребителски интерфейс). Сега следва ръководствата на Python SDKopenai-chatkit1.6.5 (Подгответе приложението си за продукция, Предайте допълнителен контекст на приложението, Актуализирайте клиента по време на отговор) и типовете на@openai/chatkit-react1.6.1: сървърният код е изпълнен локално, а React кодът е проверен чрез компилация. Източници: Подгответе приложението си за продукция · Предайте допълнителен контекст на приложението си на модела · Актуализирайте клиента по време на отговор · Разширени интеграции с ChatKit.
Какво остава след демонстрацията
Първите четири урока Ви осигуряват работещ асистент. За да го внедрите в реален продукт, той се нуждае от онова, което отличава демонстрацията от услугата: да знае кой говори, да показва на всеки потребител само неговите разговори, да взаимодейства с останалата част от приложението и да бъде наблюдаем. Този урок разглежда тези точки една по една.
Удостоверяване на всяка заявка
SDK не прави никакви предположения относно Вашата автентикация: то Ви позволява да проверите потребителя и след това да предадете неговата идентичност на server.process в контекста на заявката. Този контекст придружава всяко извикване: ще го откриете в respond, в action, в хранилището и в инструментите на агента.
От страна на интерфейса, опцията api.fetch замества функцията fetch, използвана от ChatKit. Тук добавяте токена на сесията на Вашето приложение:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function ConnectedAssistant({ obtainToken }: { obtainToken: () => Promise<string> }) {
const { control } = useChatKit({
api: {
url: '/chatkit',
domainKey: 'local-dev',
fetch: async (input, init) => {
// Запазете заглавките, зададени от ChatKit, след това добавете нашите
const headers = new Headers(init?.headers);
headers.set('Authorization', `Bearer ${await obtainToken()}`);
return fetch(input, { ...init, headers });
},
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
От страна на сървъра, зависимост на FastAPI проверява токена и изгражда контекста. Езикът на интерфейса пристига в заглавката Accept-Language, която ChatKit изпраща с всяка заявка:
from dataclasses import dataclass
from chatkit.server import StreamingResult
from chatkit.store import NotFoundError
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import Response, StreamingResponse
@dataclass
class RequestContext:
user_id: str
locale: str
async def current_user(request: Request) -> str:
token = request.headers.get("authorization", "").removeprefix("Bearer ")
user_id = await verify_token(token) # Вашата автентикация: сесия, JWT...
if not user_id:
raise HTTPException(status_code=401, detail="Unauthenticated")
return user_id
app = FastAPI()
@app.post("/chatkit")
async def chatkit_endpoint(request: Request, user_id: str = Depends(current_user)) -> Response:
context = RequestContext(user_id=user_id, locale=request.headers.get("accept-language", "fr"))
try:
result = await server.process(await request.body(), context)
except NotFoundError:
raise HTTPException(status_code=404, detail="Not found")
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")
Всеки потребител получава собствените си разговори
Автентикацията не е достатъчна; имате нужда и от оторизация. Без контрол потребител, който познае ID на нишка, би могъл да прочете чужд разговор. Правилното място за този контрол е хранилището, през което минават всички четения. В този пример всяка нишка запазва името на своя собственик в своите метаданни, които SDK никога не предава на интерфейса:
from chatkit.store import NotFoundError
from chatkit.types import Page, ThreadMetadata
from memory_store import MemoryStore
class UserStore(MemoryStore):
async def save_thread(self, thread: ThreadMetadata, context: RequestContext) -> None:
thread.metadata.setdefault("owner", context.user_id)
await super().save_thread(thread, context)
async def load_thread(self, thread_id: str, context: RequestContext) -> ThreadMetadata:
thread = await super().load_thread(thread_id, context)
if thread.metadata.get("owner") != context.user_id:
raise NotFoundError(f"Thread {thread_id} not found") # не разкривайте, че съществува
return thread
async def load_threads(self, limit, after, order, context: RequestContext) -> Page[ThreadMetadata]:
page = await super().load_threads(limit, after, order, context)
page.data = [t for t in page.data if t.metadata.get("owner") == context.user_id]
return page
Блокът try в крайната точка има смисъл тук: без него директното четене на чужда нишка би завършило с грешка 500 вместо с 404; при стрийминг заявка, като добавяне на съобщение, SDK прекъсва потока, без да изпрати нищо. В продукция това филтриране се случва в самата SQL заявка (клауза WHERE owner = … също така правилно обработва страницирането). Приложете същото правило и за прикачените файлове. Документацията също Ви напомня да решите какво запазвате и за колко време: нишките съдържат текст, файлове и резултати от инструменти, следователно често лични данни.
предоставете на модела контекста на Вашето приложение
Моделът не знае нищо за страницата, която потребителят разглежда, за неговия абонамент или за отворения документ. Документацията предлага три начина да го научите:
- При всяка заявка, чрез заглавки, добавени в
api.fetch(X-Page,X-Plan…), които сървърът запазва в контекста; - При поискване, чрез сървърен инструмент, който чете
ctx.context.request_contextи извлича информацията; - В браузъра, чрез клиентски инструмент, когато информацията съществува само там (вижте следващия раздел).
Една предпазна мярка, взета от ръководството за продукция: никога не изграждайте системните инструкции на модела от стойности, идващи от потребителя, дори косвено (заглавие на нишка, тема на билет). Запазете ги фиксирани и предавайте променливия контекст като данни.
Клиентски инструменти
Някои данни съществуват само в браузъра: селекция в редактор, състояние на платно, незапазен чернова. Клиентски инструмент позволява на модела да ги поиска по средата на хода: Вашият сървър спира агента, ChatKit изпълнява Вашата функция в браузъра, след което връща резултата на сървъра, който възобновява работата.
От страна на сървъра, инструментът само прави заявката, а агентът спира на нея:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Чете текста, който потребителят е избрал на страницата.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})
assistant = Agent[AgentContext](
name="Writing Assistant",
instructions="Помогнете на потребителя да подобри текста, който избира.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
От страна на интерфейса, onClientTool получава заявката; името трябва да съвпада, а върнатият обект отива на сървъра:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Само един клиентски инструмент може да се изпълни на ход. И когато не очаквате отговор, предпочитайте ефект: сървърът излъчва ClientEffectEvent(name="refresh_cart", data={...}), от respond, action или инструмент чрез ctx.context.stream(...), а интерфейсът го получава в onEffect, без да прекъсва отговора. Ефектите не се записват в нишката.
Управлявайте ChatKit от Вашето приложение
useChatKit връща, в допълнение към control, методи за командване на интерфейса от останалата част от Вашия код:
| Метод | Ефект |
|---|---|
sendUserMessage({ text }) | Изпраща съобщение, все едно потребителят го е написал |
setComposerValue({ text }) | Попълва предварително входната област, без да изпраща |
setThreadId(id) | Отваря съществуваща нишка или нова нишка със стойност null |
focusComposer() | Поставя курсора във входната област |
showHistory(), hideHistory() | Отваря или затваря историята на разговорите |
sendCustomAction(action) | Изпраща действие към сървъра (Урок 20) |
fetchUpdates() | Презарежда нишката от сървъра |
Бутон „Попитайте асистента“ в листовка за продукт се превръща в един ред код:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function ProductSheet({ product }: { product: string }) {
const chatkit = useChatKit({ api: { url: '/chatkit', domainKey: 'local-dev' } });
return (
<>
<button onClick={() => chatkit.sendUserMessage({ text: `Продуктът ${product} съвместим ли е с моето оборудване?` })}>
Попитайте асистента
</button>
<ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
</>
);
}
Опцията initialThread отваря конкретна нишка при монтиране, например тази, която потребителят е оставил отворена; със стойност null (стойността по подразбиране), ChatKit показва началния екран.
Наблюдавайте какво се случва
ChatKit излъчва събития: готовност (onReady), начало и край на отговор (onResponseStart, onResponseEnd), промяна на нишка (onThreadChange), логове (onLog) и грешки (onError). В React това са опции за useChatKit:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onThreadChange: ({ threadId }) => rememberLastThread(threadId),
onError: ({ error }) => sendTelemetry({ name: 'chatkit.error', message: error.message }),
onLog: ({ name }) => sendTelemetry({ name: name }),
});
Ръководството за продукция настоява върху една точка: тези събития могат да съдържат лични данни и текст на съобщения. Не изпращайте цялото съдържание към Вашия инструмент за проследяване: извлечете полезните полета (име на събитието, ID на нишката, код на грешката). От страна на сървъра, логирайте всяка заявка към /chatkit, извикванията към хранилището и модела, както и грешките в инструментите, с ID на потребителя и нишката, за да можете да корелирате двете страни.
За бавни инструменти информирайте потребителя: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Търсене на Вашите поръчки…")) показва незабавен напредък, заменен от останалата част на отговора и никога не се записва в нишката.
Преди да преминете към продукция
Контролен списък, взет от официалното ръководство:
- Домейни: всяко производствено име на хост е изброено на страницата Domain allowlist на платформата на OpenAI, а неговият ключ е в
domainKey; - Автентикация и оторизация: всяка заявка към
/chatkitе удостоверена, нишките и прикачените файлове се филтрират по потребител; - Секрети: API ключът и вътрешните удостоверителни данни са в променливи на средата или мениджър на секрети, никога в хранилището;
- Входове: съобщенията, файловете, полезните товари на действията и резултатите от инструментите се третират като ненадеждни и се валидират, преди да достигнат до Вашите системи;
- Лични данни: периодът на съхранение е решен и приложен в хранилището, криптиране в покой, няма ненужни данни в метаданните;
- Език: езикът от
Accept-Languageуправлява отговорите на агента и съобщенията на Вашите инструменти; - Проследяване: събитията от интерфейса и сървърните логове се събират, без чувствително съдържание.
Ключови изводи
- Идентичността на потребителя преминава чрез
api.fetchот страна на интерфейса, след това чрез контекста наserver.process, който я разпространява навсякъде - Оторизацията се случва в хранилището: всяка нишка принадлежи на потребител, а нишката на друг потребител е „неоткрита“
- Контекстът на приложението пристига чрез заглавки, сървърни инструменти или клиентски инструменти (
onClientTool+StopAtTools); ефектите (onEffect) служат, когато не се очаква отговор - Методите от
useChatKit(sendUserMessage,setThreadId,setComposerValue…) командват ChatKit от останалата част на приложението - Събитията (
onError,onLog…) захранват Вашето проследяване, без да копират лични данни в него; контролният списък за продукция обхваща домейни, права, секрети, входове и данни