Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Avanceret integration i din app

Lektion 21 af 25 Opdateret 3. november 2026 Udvikler
På denne side
  1. Hvad mangler efter demo’en
  2. Godkend hver anmodning
  3. Hver bruger får deres egne samtaler
  4. Giv modellen din app-kontekst
  5. Klient-side værktøjer
  6. Styr ChatKit fra din applikation
  7. Observer, hvad der sker
  8. Før du går i produktion
  9. Vigtige pointer

Lektion omskrevet 3. november 2026. Den tidligere version stolede på opdigtede egenskaber og begivenheder (ChatProvider, “sidebar”-tilstand, UI-baseret persistens). Den følger nu Python SDK openai-chatkit 1.6.5-guides (Prepare your app for production, Pass extra app context, Update the client during a response) og @openai/chatkit-react 1.6.1-typer: serverkoden er blevet kørt lokalt, og React-koden er verificeret via kompilering. Kilder: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.

Hvad mangler efter demo’en

De foregående fire lektioner giver dig en fungerende assistent. For at gøre den levende i et rigtigt produkt, har den brug for det, der adskiller en demo fra en tjeneste: at vide, hvem der taler, kun vise hver bruger deres egne samtaler, interagere med resten af applikationen og være observerbar. Denne lektion dækker disse punkter én efter én.

Godkend hver anmodning

SDK’en gør ingen antagelser om din autentificering: den lader dig verificere brugeren og derefter sende deres identitet til server.process i en anmodningskontekst. Denne kontekst følger med hvert kald: du finder den i respond, i action, i store, og i agentens værktøjer.

På grænsefladesiden erstatter indstillingen api.fetch den fetch-funktion, som ChatKit bruger. Det er her, du tilføjer din applikations sessionstoken:

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) => {
        // Behold headers sat af ChatKit, og tilføj derefter vores
        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]" />;
}

På serversiden verificerer en FastAPI-afhængighed tokenet og bygger konteksten. Grænsefladesproget ankommer i Accept-Language-headeren, som ChatKit sender med hver anmodning:

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)  # din autentificering: 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")

Hver bruger får deres egne samtaler

Autentificering er ikke nok: du har også brug for autorisation. Uden kontrol kunne en bruger, der gætter et tråd-ID, læse en anden persons samtale. Det rette sted for denne kontrol er store, hvorigennem alle læsninger passerer. I dette eksempel gemmer hver tråd ejerns navn i sine metadata, hvilket SDK’en aldrig transmitterer til grænsefladen:

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")  # afslør ikke, at den eksisterer
        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-blokken i endpointet giver mening her: uden den ville direkte læsning af en anden brugers tråd ende i en 500-fejl i stedet for en 404; for en streamet anmodning, som at tilføje en besked, afbryder SDK’en streamen uden at sende noget. I produktion sker denne filtrering i selve SQL-forespørgslen (en WHERE owner = … håndterer også paginering korrekt). Anvend samme regel på vedhæftede filer. Dokumentationen minder dig også om at beslutte, hvad du gemmer, og hvor længe: tråde indeholder tekst, filer og værktøjsresultater, så ofte personlige data.

Giv modellen din app-kontekst

Modellen ved intet om den side, brugeren ser på, deres abonnement eller det åbne dokument. Dokumentationen foreslår tre måder at lære den dette på:

  • Ved hver anmodning, via headers tilføjet i api.fetch (X-Page, X-Plan…), som serveren gemmer i konteksten;
  • Efter behov, via et serverværktøj, der læser ctx.context.request_context og henter informationen;
  • I browseren, via et klient-side værktøj, når informationen kun eksisterer der (se næste afsnit).

Én forholdsregel, taget fra produktionsguiden: byg aldrig modellens systeminstruktioner ud fra værdier, der kommer fra brugeren, selv indirekte (trådtitel, tickets emne). Hold dem faste, og send den variable kontekst som data.

Klient-side værktøjer

Nogle informationer lever kun i browseren: markering i en editor, canvas-tilstand, en ikke-gemt kladde. Et klient-side værktøj lader modellen anmode om dem midt i en tur: din server pauser agenten, ChatKit udfører din funktion i browseren, og returnerer derefter resultatet til serveren, som genoptager processen.

På serversiden foretager værktøjet kun anmodningen, og agenten stopper ved den:

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]),
)

På grænsefladesiden modtager onClientTool anmodningen; navnet skal matche, og det returnerede objekt sendes til serveren:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Kun ét klient-side værktøj kan udføres pr. tur. Og når du ikke forventer et svar, foretrækkes en effekt: serveren udsender en ClientEffectEvent(name="refresh_cart", data={...}), fra respond, action eller et værktøj via ctx.context.stream(...), og grænsefladen modtager den i onEffect uden at afbryde svaret. Effekter registreres ikke i tråden.

Styr ChatKit fra din applikation

useChatKit returnerer, udover control, metoder til at kommandere grænsefladen fra resten af din kode:

MetodeEffekt
sendUserMessage({ text })Sender en besked, som om brugeren havde skrevet den
setComposerValue({ text })Udfylder inputområdet uden at sende
setThreadId(id)Åbner en eksisterende tråd, eller en ny tråd med null
focusComposer()Placerer markøren i inputområdet
showHistory(), hideHistory()Åbner eller lukker samtalehistorikken
sendCustomAction(action)Sender en handling til serveren (Lektion 20)
fetchUpdates()Genindlæser tråden fra serveren

En knap „Spørg assistenten” på et produktark bliver til én linje kode:

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]" />
    </>
  );
}

Indstillingen initialThread åbner en specifik tråd ved montering, for eksempel den, brugeren havde åben; med null (standardværdien) viser ChatKit startskærmen.

Observer, hvad der sker

ChatKit udsender begivenheder: klar (onReady), svar start og slut (onResponseStart, onResponseEnd), trådændring (onThreadChange), logs (onLog) og fejl (onError). I React er disse indstillinger for 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 }),
});

Produktionsguiden insisterer på ét punkt: disse begivenheder kan indeholde personlige data og beskedtekst. Send ikke alt indhold til dit sporingsværktøj: udtræk nyttige felter (begivenhedsnavn, tråd-ID, fejlkode). På serversiden skal du logge hver anmodning til /chatkit, kald til store og modellen samt værktøjsfejl med bruger- og tråd-ID, så du kan korrelere begge sider.

For langsomme værktøjer skal du holde brugeren informeret: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) viser øjeblikkelig fremdrift, erstattes af resten af svaret og registreres aldrig i tråden.

Før du går i produktion

Tjeklisten, taget fra den officielle guide:

  • Domæner: hvert produktionsværtsnavn er opført på siden Domain allowlist på OpenAI-platformen, og dets nøgle er i domainKey;
  • Autentificering og autorisation: hver anmodning til /chatkit er autentificeret, tråde og vedhæftede filer filtreres efter bruger;
  • Hemmeligheder: API-nøglen og interne legitimationsoplysninger er i miljøvariabler eller en hemmelighedsadministrator, aldrig i repositoryet;
  • Inputs: beskeder, filer, action-payloads og værktøjsresultater behandles som ikke-betroede og valideres, før de når dine systemer;
  • Personlige data: opbevaringsperiode besluttet og anvendt i store, kryptering i hvile, ingen unødvendige data i metadata;
  • Sprog: sproget Accept-Language styrer agentens svar og dine værktøjsbeskeder;
  • Sporing: grænsefladebegivenheder og serverlogs indsamles uden følsomt indhold.

Vigtige pointer

  • Brugerens identitet sendes via api.fetch på grænsefladesiden og derefter via konteksten for server.process, som spreder den overalt
  • Autorisation sker i store: hver tråd tilhører en bruger, og en anden brugers tråd er „ikke fundet”
  • App-kontekst ankommer via headers, serverværktøjer eller klient-side værktøjer (onClientTool + StopAtTools); effekter (onEffect) bruges, når intet svar forventes
  • Metoder fra useChatKit (sendUserMessage, setThreadId, setComposerValue…) kommanderer ChatKit fra resten af applikationen
  • Begivenheder (onError, onLog…) fodrer din sporing uden at kopiere personlige data ind i den; produktionschecklisten dækker domæner, rettigheder, hemmeligheder, inputs og data