Toiminnot
Tällä sivulla
Oppitunti kirjoitettu uudelleen 3. marraskuuta 2026. Edellinen versio käsitteli napsautuksia mukautetuissa React-komponenteissa ja keksi “ehdotustoimintoja”. ChatKitissä toiminto on olio, joka on liitetty widget-komponenttiin (painike, luettelon rivi, lomake). Oletusarvoisesti se käsitellään palvelimellasi luokan
ChatKitServermetodissaaction, tai selaimessa, jos määrität toisin. Tämä oppitunti noudattaa opasta Actions in ChatKit jaopenai-chatkitSDK:n versiota 1.6.5. Palvelin, mallipohjat ja lomake ajettiin paikallisesti; React-koodi varmistettiin kääntämällä. Lähteet: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Mikä on toiminto?
Widget, joka vain näyttää sisältöä, on pelkkä kaunis vastaus. Toiminnot tekevät siitä hyödyllisen: “Peruuta tilaus” -painikkeen napsauttaminen, rivin valitseminen luettelosta tai lomakkeen lähettäminen käynnistää käsittelyn ilman, että käyttäjän tarvitsee kirjoittaa viestiä. ChatKit lähettää toiminnon palvelimellesi, joka voi toimia järjestelmissäsi, päivittää widgetin, lisätä vastauksen ketjuun tai käynnistää agentin uudelleen.
Ilmoitat toiminnon widgetin mallipohjassa komponentille, joka hyväksyy sellaisen (onClickAction komponenteille Button tai ListViewItem, onChangeAction komponentille Select, onSubmitAction komponentille Form, sekä confirm ja cancel komponentille Card). Se on pieni JSON-olio:
| Kenttä | Rooli |
|---|---|
type | Toiminnon nimi, jonka koodisi testaa: "order.cancel" |
payload | Hyödyllinen data: {"number": "C-42"} |
handler | "server" (oletus) tai "client" käsittelyä varten selaimessa |
loadingBehavior | Käsittelyn aikana näytettävä lataustila (katso alta) |
Toiminnon käsittely palvelimella
Otetaan esimerkkinä tilauskortti, joka tarjoaa peruutusmahdollisuuden. Mallipohja ilmoittaa toiminnon kortin Card vahvistus- ja peruutuspainikkeille:
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 }}}}}
}
"""
Palvelimen puolella lisää action-metodi luokkaasi ChatKitServer. Se vastaanottaa ketjun, toiminnon, sen lähettäneen widgetin (sender) ja kontekstisi, ja palauttaa tapahtumia kuten 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(...) : kuten oppitunnissa 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", ""))
# Payload tulee selaimesta: tarkista oikeudet uudelleen
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)
# Jälki mallille, ei koskaan näytetä käyttäjälle
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.")
Tästä koodista nousee esiin kolme sääntöä:
- Payload ei ole luotettava. Se saapuu selaimesta, jossa kuka tahansa voi muokata sitä: OpenAI:n ohje vaatii käsittelemään sitä varmentamattomana datana. Ennen peruutusta palvelin tarkistaa, että tilaus kuuluu kirjautuneelle käyttäjälle. Kontekstin
user_idon se, jonka todennettu päätepisteesi sijoittaa sinne (oppitunti 21). - Mallin on tiedettävä, mitä tapahtui. Napsautus ei ole viesti: ilman jälkeä agentti ignoraisi seuraavalla vuorolla, että tilaus on peruutettu.
HiddenContextItemlisää tämän tiedon ketjuun näyttämättä sitä. SDK tallentaa automaattisesti vain lähetetyt elementit, eikä piilotettua elementtiä saa koskaan lähettää: sinun on lisättävä se itse storeen. - Vastaus on tapahtumavirta. Tässä yksinkertainen viesti; se voisi olla päivitetty widget, joka lähetetään
stream_widget-funktiolla kuten edellisellä oppitunnilla.
Jotta agentti kommentoisi juuri tapahtunutta, käynnistä se uudelleen toiminnon jälkeen: async for event in self.respond(thread, None, context): yield event. Metodisi respond lukee ketjun uudelleen, löytää piilotetun elementin ja vastaa sen mukaisesti.
Lomakkeet
Kun syöttökenttiä (Input, Textarea, Select, Checkbox, DatePicker…) sijoitetaan Form-komponentin sisään, niiden arvot lisätään mistä tahansa kyseisestä lomakkeesta lähetetyn toiminnon payloadiin kunkin kentän nimellä:
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}
]}
]
}
"""
Lähetyksen yhteydessä action.payload sisältää kentät source, order, category ja detail. Pisteen sisältävä nimi, kuten "client.name", tuottaa sisäkkäisen arvon: payload["client"]["name"]. Jos kentän nimi törmää payloadissa jo olevaan avaimeen, kentän arvo jätetään huomiotta ja ChatKit lähettää virhetapahtuman: valitse uniikit nimet.
Lomakkeen validointi tapahtuu selaimen puolella: required ja pattern estävät lähetyksen, kunnes kenttä on kelvollinen. Tämä on käyttäjämukavuutta, ei suojausta: validoita uudelleen palvelimella, esimerkiksi Pydantic-mallilla.
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)
# action-metodissa
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.")
Rikkaampaa validointia varten, mukautetuilla virheviesteillä, dokumentaatio neuvoo siirtymään widgetin ulkopuolelle: asiakaspuolen toiminto avaa ikkunan sovelluksessasi, ja tulos palautuu ChatKitiin sendCustomAction-funktiolla. Huomaa myös, että "asForm": true -määritteellä ilmoitettu Card toimii kuin lomake: sen kentät validoidaan ja välitetään sen confirm-toimintoon.
Vahvista ennen toimintaa
Alussa ollut peruutuskortti havainnollistaa yleistettävää sääntöä: palautumaton tai arkaluonteinen toiminto vaatii nimenomaisen vahvistuksen. Tilauksen peruuttaminen, sähköpostin lähettäminen, hyvityksen tekeminen, poistaminen: agentti ehdottaa, käyttäjä vahvistaa kortilla, jossa kerrotaan selkeästi, mitä tapahtuu, ja palvelimesi – ei malli – suorittaa toiminnon oikeudet uudelleen tarkistettuaan. Kortin Card painikkeet confirm ja cancel on tehty tätä varten. Niiden oletusarvoinen lataustila harmaannuttaa koko kortin käsittelyn ajaksi, mikä estää kaksoisnapsautukset.
Toiminnon käsittely selaimessa
Joillakin toiminnoilla ei ole tekemistä palvelimen kanssa: sivun avaaminen sovelluksessasi, linkin kopioiminen, modaalisen ikkunan näyttäminen. Ilmoita ne mallipohjassa määritteellä "handler": "client", esimerkiksi {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Ne saapuvat sitten käyttöliittymän widgets.onAction-asetukseen:
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');
// Ilmoita palvelimelle, joka voi päivittää widgetin
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction lähettää toiminnon palvelimellesi ikään kuin se olisi tullut widgetistä. Se toimii myös ChatKitin ulkopuolella: sivusi painike voi kutsua chatkit.sendCustomAction({ type: 'cart.empty' }), jolloin avustaja reagoi siihen, mitä muualla sovelluksessa tapahtuu.
Lataustilat
loadingBehavior ohjaa sitä, mitä käyttäjä näkee toiminnon käsittelyn aikana:
| Arvo | Vaikutus |
|---|---|
auto (oletus) | Mukautuu komponenttiin: vain painike komponentille Button, ei mitään komponentille Select, koko kortti komponentin Card kohdalle confirm |
self | Lataustila vain sillä yksittäisellä komponentilla, jolla toiminto on |
container | Koko widget himmenee ja muuttuu inaktiiviseksi |
none | Ei lataustilaa |
Dokumentaatio suosittelee auto-arvon käyttämistä, ellei sinulla ole erityistarvetta. Oletusarvoisesti widgetin toiminnot ovat myös estettyjä vastauksen suoratoiston aikana ristiriitojen välttämiseksi. SDK-version 1.6.2 jälkeen toiminto, joka on ilmoitettu määritteellä "streaming": false, ohittaa tämän eston: palvelimen sync_action-metodi käsittelee sen, ja se on varattu toiminnoille, jotka vain päivittävät omaa widgettiään tai toimivat ketjun ulkopuolella.
Keskeiset asiat
- Toiminto on olio
{type, payload, handler, loadingBehavior}, joka on liitetty widget-komponenttiin; se käynnistää käsittelyn ilman käyttäjän viestiä - Palvelimella luokan
ChatKitServermetodiactionvastaanottaa sen ja palauttaa tapahtumia: viestin, päivitetyn widgetin tai uuden agenttivastauksen funktionrespondkautta - Payload tulee selaimesta: varmista oikeudet ja data uudelleen palvelimella (Pydantic), vaikka lomake validoisi jo
requiredjapattern-ehdot HiddenContextItem, joka lisätään manuaalisesti storeen, kertoo mallille, mitä käyttäjä teki- Arkaluonteiset toiminnot kulkevat vahvistuskortin kautta; puhtaasti paikalliset toiminnot käsitellään selaimessa (
handler: "client",widgets.onAction,sendCustomAction)