Actions utilisateur
På denna sida
Leçon réécrite le 3 novembre 2026. La version précédente gérait les clics dans des composants React personnalisés et inventait des « actions de suggestion ». Dans ChatKit, une action est un objet attaché à un composant widget (bouton, ligne de liste, formulaire). Par défaut, elle est traitée sur votre serveur dans la méthode
actiondeChatKitServer, ou dans le navigateur si vous le spécifiez autrement. Cette leçon suit le guide Actions in ChatKit et le SDKopenai-chatkit1.6.5. Le serveur, les modèles et le formulaire ont été exécutés localement ; le code React a été vérifié par compilation. Sources : Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
Qu’est-ce qu’une action ?
Un widget qui se contente d’afficher du contenu n’est qu’une jolie réponse. Les actions le rendent utile : cliquer sur « Annuler la commande », sélectionner une ligne dans une liste ou soumettre un formulaire déclenche un traitement sans que l’utilisateur ait à taper un message. ChatKit envoie l’action à votre serveur, qui peut agir sur vos systèmes, mettre à jour le widget, ajouter une réponse au fil de discussion ou redémarrer l’agent.
Vous déclarez une action dans le modèle du widget sur un composant qui en accepte une (onClickAction pour un Button ou ListViewItem, onChangeAction pour un Select, onSubmitAction pour un Form, confirm et cancel pour un Card). C’est un petit objet JSON :
| Champ | Rôle |
|---|---|
type | Le nom de l’action que votre code teste : "order.cancel" |
payload | Données utiles : {"number": "C-42"} |
handler | "server" (par défaut) ou "client" pour le traiter dans le navigateur |
loadingBehavior | L’état de chargement affiché pendant le traitement (voir ci-dessous) |
Traitement d’une action sur le serveur
Prenons une carte de commande qui propose une annulation. Le modèle déclare l’action sur les boutons de confirmation et d’annulation de la 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 }}}}}
}
"""
Côté serveur, ajoutez une méthode action à votre ChatKitServer. Elle reçoit le fil de discussion, l’action, le widget qui l’a émise (sender) et votre contexte, et retourne des événements comme 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(...) : comme dans la leçon 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", ""))
# Le payload vient du navigateur : revérifiez les 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)
# Une trace pour le modèle, jamais affichée à l'utilisateur
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.")
Trois règles se dégagent de ce code :
- Le payload n’est pas fiable. Il arrive depuis le navigateur, où n’importe qui peut le modifier : le guide OpenAI exige de le traiter comme une donnée non vérifiée. Avant d’annuler, le serveur vérifie que la commande appartient bien à l’utilisateur authentifié. Le
user_iddans le contexte est celui que votre point de terminaison authentifié y place (leçon 21). - Le modèle doit savoir ce qui s’est passé. Un clic n’est pas un message : sans trace, l’agent ignorerait au tour suivant que la commande est annulée. Un
HiddenContextItemajoute cette information au fil de discussion sans l’afficher. Le SDK n’enregistre automatiquement que les éléments diffusés, et un élément caché ne doit jamais être diffusé : vous devez l’ajouter vous-même au store. - La réponse est un flux d’événements. Ici un simple message ; cela pourrait être un widget mis à jour, diffusé avec
stream_widgetcomme dans la leçon précédente.
Pour que l’agent commente ce qui vient de se produire, redémarrez-le après l’action : async for event in self.respond(thread, None, context): yield event. Votre méthode respond relit le fil de discussion, trouve l’élément caché et répond en conséquence.
Formulaires
Lorsque des champs de saisie (Input, Textarea, Select, Checkbox, DatePicker…) sont placés dans un Form, leurs valeurs sont ajoutées au payload de toute action émise depuis ce formulaire, sous le nom de chaque champ :
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}
]}
]
}
"""
À la soumission, action.payload contient source, order, category et detail. Un nom pointé, "client.name", produit une valeur imbriquée : payload["client"]["name"]. Si un nom de champ entre en collision avec une clé déjà présente dans le payload, la valeur du champ est ignorée et ChatKit émet un événement d’erreur : choisissez des noms distincts.
La validation du formulaire se fait côté navigateur : required et pattern bloquent la soumission tant qu’un champ est invalide. C’est un confort utilisateur, pas une protection : re-validez sur le serveur, par exemple avec un modèle 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)
# Dans la méthode 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.")
Pour une validation plus riche, avec des messages d’erreur personnalisés, la documentation conseille de sortir du widget : une action côté client ouvre une fenêtre dans votre application, et le résultat revient à ChatKit via sendCustomAction. Notez aussi qu’une Card déclarée avec "asForm": true se comporte comme un formulaire : ses champs sont validés et passés à son action confirm.
Confirmer avant d’agir
La carte d’annulation du début illustre une règle à généraliser : une action irréversible ou sensible nécessite une confirmation explicite. Annuler une commande, envoyer un e-mail, rembourser, supprimer : l’agent propose, l’utilisateur valide sur une carte qui indique clairement ce qui va se passer, et c’est votre serveur, pas le modèle, qui exécute après avoir revérifié les permissions. Les boutons confirm et cancel d’une Card sont faits pour cela. Leur état de chargement par défaut grise toute la carte pendant le traitement, ce qui empêche les doubles clics.
Traitement d’une action dans le navigateur
Certaines actions n’ont rien à faire sur le serveur : ouvrir une page dans votre application, copier un lien, afficher une modale. Déclarez-les avec "handler": "client" dans le modèle, par exemple {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Elles arrivent alors dans l’option widgets.onAction de l’interface :
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');
// Notifier le serveur, qui peut mettre à jour le widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction envoie une action à votre serveur comme si elle venait d’un widget. Cela fonctionne aussi hors de ChatKit : un bouton sur votre page peut appeler chatkit.sendCustomAction({ type: 'cart.empty' }) pour que l’assistant réagisse à ce qui se passe ailleurs dans l’application.
États de chargement
loadingBehavior contrôle ce que l’utilisateur voit pendant le traitement d’une action :
| Valeur | Effet |
|---|---|
auto (par défaut) | S’adapte au composant : le bouton seul pour un Button, rien pour un Select, toute la carte pour le confirm d’une Card |
self | État de chargement sur le composant unique détenant l’action |
container | Tout le widget s’estompe et devient inactif |
none | Aucun état de chargement |
La documentation recommande de garder auto, sauf besoin spécifique. Par défaut, les actions sur un widget sont aussi bloquées pendant qu’une réponse est diffusée, pour éviter les conflits. Depuis la version 1.6.2 du SDK, une action déclarée avec "streaming": false contourne ce blocage : elle est traitée par la méthode sync_action du serveur, réservée aux actions qui ne mettent à jour que leur propre widget ou agissent hors du fil de discussion.
Viktiga punkter
- Une action est un objet
{type, payload, handler, loadingBehavior}attaché à un composant widget ; elle déclenche un traitement sans message utilisateur - Sur le serveur, la méthode
actiondeChatKitServerla reçoit et retourne des événements : message, widget mis à jour, ou nouvelle réponse de l’agent viarespond - Le payload vient du navigateur : revérifiez les permissions et les données sur le serveur (Pydantic), même si le formulaire valide déjà
requiredetpattern - Un
HiddenContextItem, ajouté manuellement au store, informe le modèle de ce que l’utilisateur a fait - Les actions sensibles passent par une carte de confirmation ; les actions purement locales sont traitées dans le navigateur (
handler: "client",widgets.onAction,sendCustomAction)