Przejdź do głównej treści
Polski— Wybierz język
Menu

Zaawansowana integracja w Twojej aplikacji

Lekcja 21 z 25 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Co pozostało po demie
  2. Uwierzytelniaj każde żądanie
  3. Każdy użytkownik ma swoje własne konwersacje
  4. Przekaż modelowi kontekst swojej aplikacji
  5. Narzędzia po stronie klienta
  6. Steruj ChatKit ze swojej aplikacji
  7. Obserwuj, co się dzieje
  8. Zanim przejdziesz do produkcji
  9. Kluczowe wnioski

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 SDK openai-chatkit 1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) oraz typami @openai/chatkit-react 1.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_context i 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:

MetodaEfekt
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 /chatkit jest 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-Language steruje 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.fetch po stronie interfejsu, a następnie przez kontekst server.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