Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Brugerhandlinger

Lektion 20 af 25 Opdateret 3. november 2026 Udvikler
På denne side
  1. Hvad er en handling?
  2. Behandling af en handling på serveren
  3. Formularer
  4. Bekræft før handling
  5. Behandling af en handling i browseren
  6. Indlæsningstilstande
  7. Vigtige pointer

Lektion omskrevet 3. november 2026. Den tidligere version håndterede klik i brugerdefinerede React-komponenter og opfandt “forslagshandlinger”. I ChatKit er en handling et objekt knyttet til en widget-komponent (knap, listerække, formular). Som standard behandles den på din server i action-metoden i ChatKitServer, eller i browseren, hvis du angiver andet. Denne lektion følger guiden Actions in ChatKit og openai-chatkit SDK 1.6.5. Serveren, skabelonerne og formularen blev kørt lokalt; React-koden blev verificeret ved kompilering. Kilder: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.

Hvad er en handling?

En widget, der kun viser indhold, er blot et pænt svar. Handlinger gør den nyttig: At klikke på “Annuller ordre”, vælge en række i en liste eller indsende en formular udløser behandling uden at brugeren behøver at skrive en besked. ChatKit sender handlingen til din server, som kan handle på dine systemer, opdatere widgetten, tilføje et svar til tråden eller genstarte agenten.

Du erklærer en handling i widget-skabelonen på en komponent, der accepterer en (onClickAction for en Button eller ListViewItem, onChangeAction for en Select, onSubmitAction for en Form, confirm og cancel for en Card). Det er et lille JSON-objekt:

FeltRolle
typeHandlingsnavnet, som din kode tester: "order.cancel"
payloadNyttige data: {"number": "C-42"}
handler"server" (standard) eller "client" for at behandle den i browseren
loadingBehaviorIndlæsningstilstanden, der vises under behandlingen (se nedenfor)

Behandling af en handling på serveren

Lad os tage et ordrekort, der tilbyder annullering. Skabelonen erklærer handlingen på bekræftelses- og annulleringsknapperne på Card:

CANCEL_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
    {"type": "Text", "value": "Do you really want to cancel this order?"}
  ],
  "confirm": {"label": "Cancel Order",
              "action": {"type": "order.cancel", "payload": {"number": {{ number | tojson }}}}},
  "cancel": {"label": "Keep Order",
             "action": {"type": "order.keep", "payload": {"number": {{ number | tojson }}}}}
}
"""

På serversiden tilføjer du en action-metode til din ChatKitServer. Den modtager tråden, handlingen, widgetten der udsendte den (sender), og din kontekst, og returnerer begivenheder som respond:

from datetime import datetime
from typing import Any, AsyncIterator

from chatkit.actions import Action
from chatkit.server import ChatKitServer
from chatkit.types import (
    AssistantMessageContent,
    AssistantMessageItem,
    HiddenContextItem,
    ThreadItemDoneEvent,
    ThreadMetadata,
    ThreadStreamEvent,
    WidgetItem,
)


class MyChatKitServer(ChatKitServer[dict[str, Any]]):
    # respond(...) : as in lesson 17

    def message(self, thread: ThreadMetadata, context: dict[str, Any], text: str) -> ThreadItemDoneEvent:
        return ThreadItemDoneEvent(
            item=AssistantMessageItem(
                thread_id=thread.id,
                id=self.store.generate_item_id("message", thread, context),
                created_at=datetime.now(),
                content=[AssistantMessageContent(text=text)],
            )
        )

    async def action(
        self,
        thread: ThreadMetadata,
        action: Action[str, Any],
        sender: WidgetItem | None,
        context: dict[str, Any],
    ) -> AsyncIterator[ThreadStreamEvent]:
        if action.type == "order.cancel":
            number = str((action.payload or {}).get("number", ""))
            # The payload comes from the browser: re-verify permissions
            if not await is_user_order(number, context.get("user_id")):
                yield self.message(thread, context, "This order does not belong to you.")
                return
            await cancel_order(number)
            # A trace for the model, never shown to the user
            await self.store.add_thread_item(
                thread.id,
                HiddenContextItem(
                    id=self.store.generate_item_id("message", thread, context),
                    thread_id=thread.id,
                    created_at=datetime.now(),
                    content=f"<USER_ACTION>User canceled order {number}.</USER_ACTION>",
                ),
                context,
            )
            yield self.message(thread, context, f"Done: order {number} is canceled.")
        elif action.type == "order.keep":
            yield self.message(thread, context, "Very well, the order is kept.")

Tre regler fremgår af denne kode:

  • Payloaden er ikke betroet. Den ankommer fra browseren, hvor alle kan modificere den: OpenAI-guiden kræver, at du behandler den som ubekræftede data. Før annullering tjekker serveren, at ordren tilhører den autentificerede bruger. user_id i konteksten er den, dit autentificerede endpoint placerer der (lektion 21).
  • Modellen skal vide, hvad der skete. Et klik er ikke en besked: uden et spor ville agenten ignorere ved næste tur, at ordren er annulleret. En HiddenContextItem tilføjer denne information til tråden uden at vise den. SDK’en registrerer automatisk kun broadcast-elementer, og et skjult element må aldrig broadcastes: du skal selv tilføje det til store.
  • Svaret er en strøm af begivenheder. Her en simpel besked; det kunne være en opdateret widget, broadcastet med stream_widget som i den forrige lektion.

For at få agenten til at kommentere det, der lige skete, genstart den efter handlingen: async for event in self.respond(thread, None, context): yield event. Din respond-metode genlæser tråden, finder det skjulte element og svarer i overensstemmelse hermed.

Formularer

Når inputfelter (Input, Textarea, Select, Checkbox, DatePicker…) placeres inde i en Form, tilføjes deres værdier til payloaden for enhver handling udsendt fra den formular under hvert felts navn:

REPORT_TEMPLATE = """
{
  "type": "Card",
  "children": [
    {"type": "Form", "direction": "col", "gap": 3,
     "onSubmitAction": {"type": "ticket.create", "payload": {"source": "chat"}},
     "children": [
       {"type": "Title", "value": "Report an Issue", "size": "sm"},
       {"type": "Label", "value": "Order Number", "fieldName": "order"},
       {"type": "Input", "name": "order", "required": true, "pattern": "C-[0-9]+", "placeholder": "C-42"},
       {"type": "Label", "value": "Category", "fieldName": "category"},
       {"type": "Select", "name": "category", "placeholder": "Select",
        "options": [{"label": "Damaged Package", "value": "damaged"},
                    {"label": "Delay", "value": "delay"},
                    {"label": "Other", "value": "other"}]},
       {"type": "Textarea", "name": "detail", "rows": 3, "placeholder": "Describe the issue"},
       {"type": "Button", "label": "Submit", "submit": true}
     ]}
  ]
}
"""

Ved indsendelse indeholder action.payload source, order, category og detail. Et prikket navn, "client.name", producerer en nested værdi: payload["client"]["name"]. Hvis et feltnavn kolliderer med en nøgle, der allerede findes i payloaden, ignoreres feltværdien, og ChatKit udsender en fejl begivenhed: vælg distinkte navne.

Formularvalidering sker på browsersiden: required og pattern blokerer indsendelse, mens et felt er ugyldigt. Dette er brugerkomfort, ikke beskyttelse: genvalider på serveren, for eksempel med en Pydantic-model.

from typing import Literal

from pydantic import BaseModel, Field, ValidationError


class Report(BaseModel):
    order: str = Field(pattern=r"^C-[0-9]+$")
    category: Literal["damaged", "delay", "other"]
    detail: str = Field(default="", max_length=2000)


# In the action method
if action.type == "ticket.create":
    try:
        report = Report.model_validate(action.payload or {})
    except ValidationError:
        yield self.message(thread, context, "The form is incomplete or invalid.")
        return
    ticket_number = await create_ticket(report, context.get("user_id"))
    yield self.message(thread, context, f"Ticket {ticket_number} created, we will get back to you.")

For rigere validering med brugerdefinerede fejlmeddelelser anbefaler dokumentationen at flytte uden for widgetten: en klient-side-handling åbner et vindue i din applikation, og resultatet returneres til ChatKit via sendCustomAction. Bemærk også, at en Card erklæret med "asForm": true opfører sig som en formular: dens felter valideres og sendes til dens confirm-handling.

Bekræft før handling

Annulleringskortet i begyndelsen illustrerer en regel, der skal generaliseres: En irreversibel eller følsom handling kræver eksplicit bekræftelse. Annullering af en ordre, afsendelse af en e-mail, refusion, sletning: agenten foreslår, brugeren validerer på et kort, der tydeligt angiver, hvad der vil ske, og det er din server, ikke modellen, der udfører handlingen efter genverificering af tilladelser. confirm- og cancel-knapperne på en Card er lavet til dette. Deres standardindlæsningstilstand gråtoner hele kortet under behandlingen, hvilket forhindrer dobbeltklik.

Behandling af en handling i browseren

Nogle handlinger har intet at gøre på serveren: åbne en side i din applikation, kopiere et link, vise en modal. Erklær dem med "handler": "client" i skabelonen, for eksempel {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. De ankommer derefter i widgets.onAction-indstillingen i grænsefladen:

import { ChatKit, useChatKit } from '@openai/chatkit-react';

export function AssistantOrders() {
  const chatkit = useChatKit({
    api: { url: '/chatkit', domainKey: 'local-dev' },
    widgets: {
      onAction: async (action, widgetItem) => {
        if (action.type === 'order.track') {
          window.open(`/orders/${String(action.payload?.number ?? '')}`, '_blank');
          // Notify the server, which can update the widget
          await chatkit.sendCustomAction(
            { type: 'order.tracked', payload: action.payload },
            widgetItem.id,
          );
        }
      },
    },
  });

  return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}

sendCustomAction sender en handling til din server, som om den kom fra en widget. Den fungerer også uden for ChatKit: en knap på din side kan kalde chatkit.sendCustomAction({ type: 'cart.empty' }), så assistenten reagerer på det, der sker andre steder i applikationen.

Indlæsningstilstande

loadingBehavior styrer, hvad brugeren ser, mens en handling behandles:

VærdiEffekt
auto (standard)Tilpasser sig komponenten: kun knappen for en Button, intet for en Select, hele kortet for confirm på en Card
selfIndlæsningstilstand på den enkelte komponent, der indeholder handlingen
containerHele widgetten falmer og bliver inaktiv
noneIngen indlæsningstilstand

Dokumentationen anbefaler at beholde auto, medmindre du har et specifikt behov. Som standard blokeres handlinger på en widget også, mens et svar streames, for at undgå konflikter. Siden SDK-version 1.6.2 omgår en handling erklæret med "streaming": false denne blokering: den behandles af serverens sync_action-metode, reserveret til handlinger, der kun opdaterer deres egen widget eller handler uden for tråden.

Vigtige pointer

  • En handling er et objekt {type, payload, handler, loadingBehavior} knyttet til en widget-komponent; den udløser behandling uden en brugerbesked
  • På serveren modtager action-metoden i ChatKitServer den og returnerer begivenheder: besked, opdateret widget eller nyt agentsvar via respond
  • Payloaden kommer fra browseren: genverificer tilladelser og data på serveren (Pydantic), selv når formularen allerede validerer required og pattern
  • En HiddenContextItem, manuelt tilføjet til store, informerer modellen om, hvad brugeren gjorde
  • Følsomme handlinger går gennem et bekræftelseskort; rent lokale handlinger behandles i browseren (handler: "client", widgets.onAction, sendCustomAction)