Zaawansowana integracja w Twojej aplikacji
Na tej stronie
Lekcja przepisana 3 listopada 2026 r. Poprzednia wersja opierała się na wymyślonych właściwościach i zdarzeniach (
ChatProvider, tryb „sidebar“, utrwalanie oparte na interfejsie). Obecnie podąża za przewodnikami Python SDKopenai-chatkit1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) oraz typami@openai/chatkit-react1.6.1: kod serwera został wykonany lokalnie, a kod React zweryfikowany przez kompilację. Źródła: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.
Co pozostało po demie
Poprzednie cztery lekcje dały Ci działającego asystenta. Aby uruchomić go w prawdziwym produkcie, potrzebuje on tego, co odróżnia demo od usługi: wiedzy o tym, kto rozmawia, pokazywania każdemu użytkownikowi tylko jego konwersacji, interakcji z resztą aplikacji oraz możliwości obserwacji. Ta lekcja omawia te punkty po kolei.
Uwierzytelniaj każde żądanie
SDK nie zakłada niczego na temat Twojego uwierzytelniania: pozwala zweryfikować użytkownika, a następnie przekazać jego tożsamość do server.process w kontekście żądania. Kontekst ten towarzyszy każdemu wywołaniu: znajdziesz go w respond, w action, w store oraz w narzędziach agenta.
Po stronie interfejsu opcja api.fetch zastępuje funkcję fetch używaną przez ChatKit. To tutaj dodajesz token sesji swojej aplikacji:
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) => {
// Keep headers set by ChatKit, then add ours
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]" />;
}
Po stronie serwera zależność FastAPI weryfikuje token i buduje kontekst. Język interfejsu dociera w nagłówku Accept-Language, który ChatKit wysyła z każdym żądaniem:
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) # your authentication: session, 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")
Każdy użytkownik ma swoje własne konwersacje
Samo uwierzytelnienie nie wystarczy: potrzebujesz również autoryzacji. Bez kontroli użytkownik, który odgadnie ID wątku, mógłby przeczytać cudzą rozmowę. Właściwym miejscem na tę kontrolę jest store, przez który przechodzą wszystkie odczyty. W tym przykładzie każdy wątek przechowuje nazwę właściciela w swoich metadanych, których SDK nigdy nie przesyła do interfejsu:
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") # do not reveal that it exists
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
Blok try w punkcie końcowym ma tu sens: bez niego bezpośredni odczyt wątku innego użytkownika zakończyłby się błędem 500 zamiast 404; w przypadku żądania strumieniowego, takiego jak dodawanie wiadomości, SDK przerywa strumień bez wysyłania czegokolwiek. W środowisku produkcyjnym to filtrowanie odbywa się w samym zapytaniu SQL (klauzula WHERE owner = … również poprawnie obsługuje paginację). Zastosuj tę samą zasadę do załączników. Dokumentacja przypomina również, aby zdecydować, co przechowujesz i jak długo: wątki zawierają tekst, pliki i wyniki działania narzędzi, więc często są to dane osobowe.
Przekaż modelowi kontekst swojej aplikacji
Model nie wie nic o stronie, którą użytkownik przegląda, o jego subskrypcji czy otwartym dokumencie. Dokumentacja proponuje trzy sposoby, aby go tego nauczyć:
- Przy każdym żądaniu, poprzez nagłówki dodane w
api.fetch(X-Page,X-Plan…), które serwer przechowuje w kontekście; - Na żądanie, poprzez narzędzie serwerowe, które odczytuje
ctx.context.request_contexti pobiera informacje; - W przeglądarce, poprzez narzędzie po stronie klienta, gdy informacje istnieją tylko tam (patrz następna sekcja).
Jedna ostrożność, zaczerpnięta z przewodnika produkcyjnego: nigdy nie buduj instrukcji systemowych modelu z wartości pochodzących od użytkownika, nawet pośrednio (tytuł wątku, temat zgłoszenia). Pozostaw je stałe, a zmienny kontekst przekaż jako dane.
Narzędzia po stronie klienta
Niektóre informacje żyją tylko w przeglądarce: zaznaczenie w edytorze, stan płótna, niezapisany szkic. Narzędzie po stronie klienta pozwala modelowi zażądać ich w trakcie tury: Twój serwer wstrzymuje agenta, ChatKit wykonuje Twoją funkcję w przeglądarce, a następnie zwraca wynik serwerowi, który wznawia działanie.
Po stronie serwera narzędzie jedynie zgłasza żądanie, a agent zatrzymuje się na nim:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Reads the text the user has selected on the page.")
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="Help the user improve the text they select.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
Po stronie interfejsu onClientTool otrzymuje żądanie; nazwa musi się zgadzać, a zwracany obiekt trafia do serwera:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Tylko jedno narzędzie po stronie klienta może zostać wykonane na turę. A gdy nie oczekujesz odpowiedzi, preferuj efekt: serwer emituje ClientEffectEvent(name="refresh_cart", data={...}), z respond, action lub narzędzia poprzez ctx.context.stream(...), a interfejs otrzymuje go w onEffect bez przerywania odpowiedzi. Efekty nie są zapisywane w wątku.
Steruj ChatKit ze swojej aplikacji
useChatKit zwraca, oprócz control, metody do wydawania poleceń interfejsowi z reszty Twojego kodu:
| Metoda | Efekt |
|---|---|
sendUserMessage({ text }) | Wysyła wiadomość, jakby użytkownik ją wpisał |
setComposerValue({ text }) | Wstępnie wypełnia obszar wprowadzania bez wysyłania |
setThreadId(id) | Otwiera istniejący wątek lub nowy wątek z wartością null |
focusComposer() | Umieszcza kursor w obszarze wprowadzania |
showHistory(), hideHistory() | Otwiera lub zamyka historię konwersacji |
sendCustomAction(action) | Wysyła akcję do serwera (Lekcja 20) |
fetchUpdates() | Przeładowuje wątek z serwera |
Przycisk „Zapytaj asystenta“ na karcie produktu staje się jedną linią kodu:
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: `Is the ${product} product compatible with my equipment?` })}>
Ask the assistant
</button>
<ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
</>
);
}
Opcja initialThread otwiera określony wątek podczas montowania komponentu, na przykład ten, który użytkownik pozostawił otwarty; przy wartości null (wartość domyślna) ChatKit wyświetla ekran główny.
Obserwuj, co się dzieje
ChatKit emituje zdarzenia: gotowość (onReady), rozpoczęcie i zakończenie odpowiedzi (onResponseStart, onResponseEnd), zmianę wątku (onThreadChange), logi (onLog) oraz błędy (onError). W React są to opcje dla 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 }),
});
Przewodnik produkcyjny nalega na jeden punkt: te zdarzenia mogą zawierać dane osobowe i tekst wiadomości. Nie wysyłaj całej zawartości do narzędzia śledzącego: ekstrahuj przydatne pola (nazwa zdarzenia, ID wątku, kod błędu). Po stronie serwera loguj każde żądanie do /chatkit, wywołania store i modelu oraz błędy narzędzi, wraz z ID użytkownika i wątku, aby móc skorelować obie strony.
Dla wolnych narzędzi informuj użytkownika na bieżąco: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) wyświetla natychmiastowy postęp, zastępowany przez resztę odpowiedzi i nigdy niezapisywany w wątku.
Zanim przejdziesz do produkcji
Lista kontrolna, zaczerpnięta z oficjalnego przewodnika:
- Domeny: każda nazwa hosta produkcyjnego jest wymieniona na stronie Domain allowlist platformy OpenAI, a jej klucz znajduje się w
domainKey; - Uwierzytelnianie i autoryzacja: każde żądanie do
/chatkitjest uwierzytelnione, wątki i załączniki są filtrowane według użytkownika; - Sekrety: klucz API i wewnętrzne dane uwierzytelniające znajdują się w zmiennych środowiskowych lub menedżerze sekretów, nigdy w repozytorium;
- Dane wejściowe: wiadomości, pliki, ładunki akcji i wyniki narzędzi są traktowane jako niezaufane i walidowane przed dotarciem do Twoich systemów;
- Dane osobowe: okres przechowywania ustalony i zastosowany w store, szyfrowanie w spoczynku, brak niepotrzebnych danych w metadanych;
- Język: język z nagłówka
Accept-Languagesteruje odpowiedziami agenta i komunikatami Twoich narzędzi; - Śledzenie: zdarzenia interfejsu i logi serwera są zbierane, bez poufnej zawartości.
Kluczowe wnioski
- Tożsamość użytkownika przechodzi przez
api.fetchpo stronie interfejsu, a następnie przez kontekstserver.process, który propaguje ją wszędzie - Autoryzacja odbywa się w store: każdy wątek należy do użytkownika, a wątek innego użytkownika jest „nieznaleziony“
- Kontekst aplikacji dociera przez nagłówki, narzędzia serwerowe lub narzędzia po stronie klienta (
onClientTool+StopAtTools); efekty (onEffect) służą, gdy nie oczekuje się odpowiedzi - Metody z
useChatKit(sendUserMessage,setThreadId,setComposerValue…) sterują ChatKit z reszty aplikacji - Zdarzenia (
onError,onLog…) zasilają Twoje śledzenie, bez kopiowania do niego danych osobowych; lista kontrolna produkcji obejmuje domeny, prawa, sekrety, dane wejściowe i dane