Ενέργειες Χρήστη
Σε αυτήν τη σελίδα
Μάθημα ξαναγραμμένο στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση διαχειριζόταν κλικ σε προσαρμοσμένα στοιχεία React και εφηύρε «προτεινόμενες ενέργειες». Στο ChatKit, μια ενέργεια είναι ένα αντικείμενο προσαρτημένο σε ένα στοιχείο widget (κουμπί, γραμμή λίστας, φόρμα). Εξ ορισμού, επεξεργάζεται στον διακομιστή σας στη μέθοδο
actionτουChatKitServer, ή στον περιηγητή αν το ορίσετε διαφορετικά. Αυτό το μάθημα ακολουθεί τον οδηγό Actions in ChatKit και το SDKopenai-chatkit1.6.5. Ο διακομιστής, τα πρότυπα και η φόρμα εκτελέστηκαν τοπικά· ο κώδικας React επαληθεύτηκε μέσω μεταγλώττισης. Πηγές: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Τι είναι μια ενέργεια;
Ένα widget που απλώς εμφανίζει περιεχόμενο είναι απλώς μια ωραία απάντηση. Οι ενέργειες το καθιστούν χρήσιμο: κάνοντας κλικ στο «Ακύρωση Παραγγελίας», επιλέγοντας μια γραμμή σε μια λίστα ή υποβάλλοντας μια φόρμα, ενεργοποιείται η επεξεργασία χωρίς ο χρήστης να χρειάζεται να πληκτρολογήσει μήνυμα. Το ChatKit στέλνει την ενέργεια στον διακομιστή σας, ο οποίος μπορεί να δράσει στα συστήματά σας, να ενημερώσει το widget, να προσθέσει μια απάντηση στο νήμα ή να επανεκκινήσει τον πράκτορα.
Δηλώνετε μια ενέργεια στο πρότυπο του widget σε ένα στοιχείο που την δέχεται (onClickAction για Button ή ListViewItem, onChangeAction για Select, onSubmitAction για Form, confirm και cancel για Card). Είναι ένα μικρό αντικείμενο JSON:
| Πεδίο | Ρόλος |
|---|---|
type | Το όνομα της ενέργειας που ελέγχει ο κώδικάς σας: "order.cancel" |
payload | Χρήσιμα δεδομένα: {"number": "C-42"} |
handler | "server" (προεπιλογή) ή "client" για επεξεργασία στον περιηγητή |
loadingBehavior | Η κατάσταση φόρτωσης που εμφανίζεται κατά την επεξεργασία (δείτε παρακάτω) |
Επεξεργασία μιας ενέργειας στον διακομιστή
Ας πάρουμε μια κάρτα παραγγελίας που προσφέρει ακύρωση. Το πρότυπο δηλώνει την ενέργεια στα κουμπιά επιβεβαίωσης και ακύρωσης της 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 }}}}}
}
"""
Στην πλευρά του διακομιστή, προσθέστε μια μέθοδο action στον ChatKitServer σας. Λαμβάνει το νήμα, την ενέργεια, το widget που την εξέπεμψε (sender) και το πλαίσιο σας, και επιστρέφει συμβάντα όπως το 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(...) : όπως στο μάθημα 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 έρχεται από τον περιηγητή: επαληθεύστε ξανά τα δικαιώματα
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)
# Ένα ίχνος για το μοντέλο, που δεν εμφανίζεται ποτέ στον χρήστη
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.")
Τρεις κανόνες προκύπτουν από αυτόν τον κώδικα:
- Το payload δεν είναι έμπιστο. Φτάνει από τον περιηγητή, όπου ο καθένας μπορεί να το τροποποιήσει: ο οδηγός της OpenAI απαιτεί να το αντιμετωπίζετε ως μη επαληθευμένα δεδομένα. Πριν την ακύρωση, ο διακομιστής ελέγχει ότι η παραγγελία ανήκει στον πιστοποιημένο χρήστη. Το
user_idστο πλαίσιο είναι αυτό που τοποθετεί το πιστοποιημένο endpoint σας (μάθημα 21). - Το μοντέλο πρέπει να γνωρίζει τι συνέβη. Ένα κλικ δεν είναι μήνυμα: χωρίς ίχνος, ο πράκτορας θα αγνοούσε στον επόμενο γύρο ότι η παραγγελία ακυρώθηκε. Ένα
HiddenContextItemπροσθέτει αυτές τις πληροφορίες στο νήμα χωρίς να τις εμφανίζει. Το SDK καταγράφει αυτόματα μόνο τα στοιχεία εκπομπής, και ένα κρυφό στοιχείο δεν πρέπει ποτέ να εκπέμπεται: πρέπει να το προσθέσετε εσείς στο store. - Η απάντηση είναι μια ροή συμβάντων. Εδώ ένα απλό μήνυμα· θα μπορούσε να είναι ένα ενημερωμένο widget, που εκπέμπεται με
stream_widgetόπως στο προηγούμενο μάθημα.
Για να σχολιάσει ο πράκτορας αυτό που μόλις συνέβη, επανεκκινήστε τον μετά την ενέργεια: async for event in self.respond(thread, None, context): yield event. Η μέθοδος respond σας ξαναδιαβάζει το νήμα, βρίσκει το κρυφό στοιχείο και απαντά ανάλογα.
Φόρμες
Όταν πεδία εισαγωγής (Input, Textarea, Select, Checkbox, DatePicker…) τοποθετούνται μέσα σε μια Form, οι τιμές τους προστίθενται στο payload οποιασδήποτε ενέργειας που εκπέμπεται από αυτή τη φόρμα, υπό το όνομα κάθε πεδίου:
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}
]}
]
}
"""
Κατά την υποβολή, το action.payload περιέχει source, order, category και detail. Ένα όνομα με τελεία, "client.name", παράγει μια εμφωλευμένη τιμή: payload["client"]["name"]. Αν ένα όνομα πεδίου συγκρούεται με ένα κλειδί που υπάρχει ήδη στο payload, η τιμή του πεδίου αγνοείται και το ChatKit εκπέμπει ένα συμβάν σφάλματος: επιλέξτε διακριτά ονόματα.
Η επικύρωση της φόρμας γίνεται στην πλευρά του περιηγητή: τα required και pattern εμποδίζουν την υποβολή ενώ ένα πεδίο είναι άκυρο. Αυτό είναι ευκολία για τον χρήστη, όχι προστασία: επανεπικυρώστε στον διακομιστή, για παράδειγμα με ένα μοντέλο Pydantic.
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
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.")
Για πλουσιότερη επικύρωση, με προσαρμοσμένα μηνύματα σφάλματος, η τεκμηρίωση συμβουλεύει να μετακινηθείτε έξω από το widget: μια ενέργεια client-side ανοίγει ένα παράθυρο στην εφαρμογή σας και το αποτέλεσμα επιστρέφει στο ChatKit μέσω sendCustomAction. Σημειώστε επίσης ότι μια Card που δηλώνεται με "asForm": true συμπεριφέρεται όπως μια φόρμα: τα πεδία της επικυρώνονται και περνούν στην ενέργεια confirm της.
Επιβεβαίωση πριν την ενέργεια
Η κάρτα ακύρωσης στην αρχή απεικονίζει έναν κανόνα που πρέπει να γενικευτεί: μια μη αναστρέψιμη ή ευαίσθητη ενέργεια απαιτεί ρητή επιβεβαίωση. Ακύρωση παραγγελίας, αποστολή email, επιστροφή χρημάτων, διαγραφή: ο πράκτορας προτείνει, ο χρήστης επικυρώνει σε μια κάρτα που δηλώνει ξεκάθαρα τι θα συμβεί, και είναι ο διακομιστής σας, όχι το μοντέλο, που εκτελεί μετά από επανέλεγχο των δικαιωμάτων. Τα κουμπιά confirm και cancel μιας Card είναι φτιαγμένα γι’ αυτό. Η προεπιλεγμένη κατάστασή τους φόρτωσης γκριζάρει ολόκληρη την κάρτα κατά την επεξεργασία, κάτι που αποτρέπει τα διπλά κλικ.
Επεξεργασία μιας ενέργειας στον περιηγητή
Ορισμένες ενέργειες δεν έχουν τίποτα να κάνουν στον διακομιστή: άνοιγμα σελίδας στην εφαρμογή σας, αντιγραφή συνδέσμου, εμφάνιση modal. Δηλώστε τις με "handler": "client" στο πρότυπο, για παράδειγμα {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Στη συνέχεια φτάνουν στην επιλογή widgets.onAction της διεπαφής:
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');
// Ειδοποιήστε τον διακομιστή, ο οποίος μπορεί να ενημερώσει το widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
Το sendCustomAction στέλνει μια ενέργεια στον διακομιστή σας σαν να προερχόταν από widget. Λειτουργεί επίσης εκτός ChatKit: ένα κουμπί στη σελίδα σας μπορεί να καλέσει chatkit.sendCustomAction({ type: 'cart.empty' }) ώστε ο βοηθός να αντιδρά σε ό,τι συμβαίνει αλλού στην εφαρμογή.
Καταστάσεις φόρτωσης
Το loadingBehavior ελέγχει τι βλέπει ο χρήστης ενώ μια ενέργεια επεξεργάζεται:
| Τιμή | Επίδραση |
|---|---|
auto (προεπιλογή) | Προσαρμόζεται στο στοιχείο: μόνο το κουμπί για Button, τίποτα για Select, ολόκληρη η κάρτα για το confirm μιας Card |
self | Κατάσταση φόρτωσης στο μεμονωμένο στοιχείο που κατέχει την ενέργεια |
container | Ολόκληρο το widget ξεθωριάζει και καθίσταται ανενεργό |
none | Καμία κατάσταση φόρτωσης |
Η τεκμηρίωση συνιστά να διατηρείτε το auto, εκτός αν έχετε συγκεκριμένη ανάγκη. Εξ ορισμού, οι ενέργειες σε ένα widget μπλοκάρονται επίσης ενώ μια απάντηση μεταδίδεται (streaming), για την αποφυγή συγκρούσεων. Από την έκδοση SDK 1.6.2, μια ενέργεια που δηλώνεται με "streaming": false παρακάμπτει αυτόν τον αποκλεισμό: επεξεργάζεται από τη μέθοδο sync_action του διακομιστή, η οποία προορίζεται για ενέργειες που ενημερώνουν μόνο το δικό τους widget ή δρουν εκτός του νήματος.
Βασικά σημεία
- Μια ενέργεια είναι ένα αντικείμενο
{type, payload, handler, loadingBehavior}προσαρτημένο σε ένα στοιχείο widget· ενεργοποιεί την επεξεργασία χωρίς μήνυμα χρήστη - Στον διακομιστή, η μέθοδος
actionτουChatKitServerτην λαμβάνει και επιστρέφει συμβάντα: μήνυμα, ενημερωμένο widget, ή νέα απάντηση πράκτορα μέσωrespond - Το payload έρχεται από τον περιηγητή: επανεπαληθεύστε δικαιώματα και δεδομένα στον διακομιστή (Pydantic), ακόμα και όταν η φόρμα έχει ήδη επικυρώσει τα
requiredκαιpattern - Ένα
HiddenContextItem, που προστίθεται χειροκίνητα στο store, ενημερώνει το μοντέλο για το τι έκανε ο χρήστης - Οι ευαίσθητες ενέργειες περνούν μέσω μιας κάρτας επιβεβαίωσης· οι καθαρά τοπικές ενέργειες επεξεργάζονται στον περιηγητή (
handler: "client",widgets.onAction,sendCustomAction)