Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Ações do Utilizador

Aula 20 de 25 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O que é uma ação?
  2. Processar uma ação no servidor
  3. Formulários
  4. Confirmar antes de agir
  5. Processar uma ação no navegador
  6. Estados de carregamento
  7. Pontos-chave

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 action do ChatKitServer, ou no navegador se especificar otherwise. Esta lição segue o guia Actions in ChatKit e o SDK openai-chatkit 1.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:

CampoFunção
typeO nome da ação que o seu código testa: "order.cancel"
payloadDados úteis: {"number": "C-42"}
handler"server" (predefinição) ou "client" para processar no navegador
loadingBehaviorO 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_id no 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 HiddenContextItem adiciona 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_widget como 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:

ValorEfeito
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
selfEstado de carregamento apenas no componente que contém a ação
containerTodo o widget esmorece e fica inativo
noneSem 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 action do ChatKitServer recebe-a e devolve eventos: mensagem, widget atualizado ou nova resposta do agente via respond
  • O payload vem do navegador: verifique novamente as permissões e os dados no servidor (Pydantic), mesmo quando o formulário já valida required e pattern
  • 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)