Ações do Utilizador
Nesta página
Lição reescrita a 3 de novembro de 2026. A versão anterior geria cliques em componentes React personalizados e inventava “ações de sugestão”. No ChatKit, uma ação é um objeto anexado a um componente de widget (botão, linha de lista, formulário). Por predefinição, é processada no seu servidor no método
actiondoChatKitServer, ou no navegador se especificar otherwise. Esta lição segue o guia Actions in ChatKit e o SDKopenai-chatkit1.6.5. O servidor, os modelos e o formulário foram executados localmente; o código React foi verificado por compilação. Fontes: Actions in ChatKit · Build interactive responses with widgets · Python SDK 1.6.2 release notes.
O que é uma ação?
Um widget que apenas apresenta conteúdo é apenas uma resposta bonita. As ações tornam-no útil: clicar em “Cancelar Encomenda”, selecionar uma linha numa lista ou submeter um formulário desencadeia um processamento sem que o utilizador tenha de escrever uma mensagem. O ChatKit envia a ação para o seu servidor, que pode atuar nos seus sistemas, atualizar o widget, adicionar uma resposta ao tópico ou reiniciar o agente.
Declara uma ação no modelo do widget num componente que a aceite (onClickAction para um Button ou ListViewItem, onChangeAction para um Select, onSubmitAction para um Form, confirm e cancel para um Card). É um pequeno objeto JSON:
| Campo | Função |
|---|---|
type | O nome da ação que o seu código testa: "order.cancel" |
payload | Dados úteis: {"number": "C-42"} |
handler | "server" (predefinição) ou "client" para processar no navegador |
loadingBehavior | O estado de carregamento apresentado durante o processamento (ver abaixo) |
Processar uma ação no servidor
Vamos pegar num cartão de encomenda que oferece a opção de cancelamento. O modelo declara a ação nos botões de confirmação e cancelamento do 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 }}}}}
}
"""
Do lado do servidor, adicione um método action ao seu ChatKitServer. Este recebe o tópico, a ação, o widget que a emitiu (sender) e o seu contexto, devolvendo eventos como 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(...) : como na lição 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", ""))
# O payload vem do navegador: verifique novamente as permissões
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)
# Um registo para o modelo, nunca mostrado ao utilizador
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.")
Três regras emergem deste código:
- O payload não é confiável. Chega do navegador, onde qualquer pessoa o pode modificar: o guia da OpenAI exige tratá-lo como dados não verificados. Antes de cancelar, o servidor verifica se a encomenda pertence ao utilizador autenticado. O
user_idno contexto é aquele que o seu endpoint autenticado lá colocou (lição 21). - O modelo tem de saber o que aconteceu. Um clique não é uma mensagem: sem um registo, o agente ignoraria na próxima interação que a encomenda foi cancelada. Um
HiddenContextItemadiciona esta informação ao tópico sem a exibir. O SDK regista automaticamente apenas elementos de difusão, e um elemento oculto nunca deve ser difundido: deve adicioná-lo manualmente ao store. - A resposta é um fluxo de eventos. Aqui uma mensagem simples; poderia ser um widget atualizado, difundido com
stream_widgetcomo na lição anterior.
Para que o agente comente o que acabou de acontecer, reinicie-o após a ação: async for event in self.respond(thread, None, context): yield event. O seu método respond relê o tópico, encontra o elemento oculto e responde em conformidade.
Formulários
Quando campos de entrada (Input, Textarea, Select, Checkbox, DatePicker…) são colocados dentro de um Form, os seus valores são adicionados ao payload de qualquer ação emitida a partir desse formulário, sob o nome de cada campo:
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}
]}
]
}
"""
Na submissão, action.payload contém source, order, category e detail. Um nome pontuado, "client.name", produz um valor aninhado: payload["client"]["name"]. Se um nome de campo colidir com uma chave já presente no payload, o valor do campo é ignorado e o ChatKit emite um evento de erro: escolha nomes distintos.
A validação do formulário ocorre no lado do navegador: required e pattern bloqueiam a submissão enquanto um campo for inválido. Isto é uma conveniência para o utilizador, não uma proteção: valide novamente no servidor, por exemplo com um modelo 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)
# No método 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.")
Para uma validação mais rica, com mensagens de erro personalizadas, a documentação aconselha sair do widget: uma ação do lado do cliente abre uma janela na sua aplicação e o resultado retorna ao ChatKit via sendCustomAction. Note também que um Card declarado com "asForm": true comporta-se como um formulário: os seus campos são validados e passados para a sua ação confirm.
Confirmar antes de agir
O cartão de cancelamento no início ilustra uma regra a generalizar: uma ação irreversível ou sensível requer confirmação explícita. Cancelar uma encomenda, enviar um e-mail, reembolsar, eliminar: o agente propõe, o utilizador valida num cartão que indica claramente o que vai acontecer, e é o seu servidor, não o modelo, que executa após verificar novamente as permissões. Os botões confirm e cancel de um Card foram feitos para isto. O seu estado de carregamento predefinido torna todo o cartão cinzento durante o processamento, o que impede duplos cliques.
Processar uma ação no navegador
Algumas ações não têm nada a fazer no servidor: abrir uma página na sua aplicação, copiar uma ligação, mostrar um modal. Declare-as com "handler": "client" no modelo, por exemplo {"type": "order.track", "handler": "client", "payload": {"number": "C-42"}}. Estas chegam então à opção widgets.onAction da 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');
// Notificar o servidor, que pode atualizar o widget
await chatkit.sendCustomAction(
{ type: 'order.tracked', payload: action.payload },
widgetItem.id,
);
}
},
},
});
return <ChatKit control={chatkit.control} className="h-[600px] w-[360px]" />;
}
sendCustomAction envia uma ação para o seu servidor como se viesse de um widget. Também funciona fora do ChatKit: um botão na sua página pode chamar chatkit.sendCustomAction({ type: 'cart.empty' }) para que o assistente reaja ao que está a acontecer noutra parte da aplicação.
Estados de carregamento
loadingBehavior controla o que o utilizador vê enquanto uma ação está a ser processada:
| Valor | Efeito |
|---|---|
auto (predefinição) | Adapta-se ao componente: apenas o botão para um Button, nada para um Select, todo o cartão para o confirm de um Card |
self | Estado de carregamento apenas no componente que contém a ação |
container | Todo o widget esmorece e fica inativo |
none | Sem estado de carregamento |
A documentação recomenda manter auto, a menos que tenha uma necessidade específica. Por predefinição, as ações num widget também são bloqueadas enquanto uma resposta está a ser transmitida em fluxo, para evitar conflitos. Desde a versão 1.6.2 do SDK, uma ação declarada com "streaming": false contorna este bloqueio: é processada pelo método sync_action do servidor, reservado para ações que apenas atualizam o seu próprio widget ou atuam fora do tópico.
Pontos-chave
- Uma ação é um objeto
{type, payload, handler, loadingBehavior}anexado a um componente de widget; desencadeia processamento sem uma mensagem do utilizador - No servidor, o método
actiondoChatKitServerrecebe-a e devolve eventos: mensagem, widget atualizado ou nova resposta do agente viarespond - O payload vem do navegador: verifique novamente as permissões e os dados no servidor (Pydantic), mesmo quando o formulário já valida
requiredepattern - Um
HiddenContextItem, adicionado manualmente ao store, informa o modelo sobre o que o utilizador fez - Ações sensíveis passam por um cartão de confirmação; ações puramente locais são processadas no navegador (
handler: "client",widgets.onAction,sendCustomAction)