Widgets Interativos
Nesta página
Lição reescrita em 3 de novembro de 2026. A versão anterior descrevia os widgets como componentes React escritos pelo programador e registados na interface, utilizando um módulo inexistente
@openai/chatkit/react. No ChatKit, um widget é uma descrição declarativa que o seu servidor constrói e que o próprio ChatKit renderiza. Esta lição segue o SDK Pythonopenai-chatkit1.6.5, que constrói widgets a partir de modelos.widget: as suas classesCard,Text,Badge… estão obsoletas. Os exemplos foram executados num servidor ChatKit local. Fontes: Widgets do ChatKit · Widgets (SDK Python) · Criar respostas interativas com widgets · Widget Builder.
O que é um widget do ChatKit?
Uma resposta textual basta para explicações. Mas para apresentar uma encomenda, comparar três planos ou confirmar um agendamento, o texto torna-se rapidamente numa parede de linhas que o utilizador tem de reler. Os widgets substituem esse texto por uma interface: um cartão, uma lista, um formulário ou um gráfico, apresentados no fluxo da conversa.
A abordagem é declarativa. O seu servidor não fornece HTML nem um componente React: descreve o widget em JSON, utilizando um conjunto fechado de componentes e propriedades, e envia-o para o tópico como um elemento completo (um WidgetItem). O ChatKit desenha-o com os seus próprios componentes, utilizando as cores do tema da lição anterior. Daí resultam duas consequências:
- Só pode utilizar componentes e propriedades que o ChatKit conhece. Em contrapartida, a renderização mantém-se consistente com o resto da interface e nenhum HTML ou JavaScript arbitrário do servidor chega à página.
- O widget faz parte do histórico: nas intervenções subsequentes, é convertido em entrada para o modelo, que assim «vê» o que mostrou ao utilizador.
Contentores e componentes
Cada widget tem uma raiz, escolhida entre três contentores:
| Contentor | Utilização |
|---|---|
Card | Conteúdo autónomo: um resumo, uma confirmação, um formulário. Aceita um estado e botões de confirmação/cancelamento abaixo do conteúdo |
ListView | Um conjunto de opções: restaurantes, ficheiros, encomendas. Os seus filhos são ListViewItem, com funcionalidade integrada de «ver mais» (limit) |
Basic | Reservado para pré-visualizações de entidades apresentadas ao passar o cursor sobre uma menção |
No interior, monta componentes: texto (Title, Text, Caption, Markdown), etiquetas (Badge), esquema (Row, Col, Box, Spacer, Divider), multimédia (Image, Icon), comandos (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, que um Form pode agrupar), gráficos (Chart) e animações (Transition). A página de Componentes do Widget Builder lista as propriedades de cada um, com um editor para os testar.
Conceção do widget no Widget Builder
O fluxo de trabalho previsto começa no Widget Builder do ChatKit Studio. Concebe aí o esquema, preenche o painel de dados com valores de exemplo para avaliar a renderização e, em seguida, exporta um ficheiro .widget. Trata-se de um ficheiro JSON que combina o modelo, o esquema dos dados esperados (jsonSchema) e os dados de exemplo. Coloque-o sob controlo de versões juntamente com o código do seu servidor, por exemplo numa pasta widgets/.
Do lado do servidor, o WidgetTemplate carrega o ficheiro e o build preenche-o com dados reais:
from chatkit.widgets import WidgetTemplate
order_template = WidgetTemplate.from_file("widgets/order.widget")
card = order_template.build({
"number": "C-42",
"status": "Shipped",
"color": "success",
"items": [{"name": "Keyboard", "price": "$49.90"}, {"name": "Mouse", "price": "$10.00"}],
"total": "$59.90",
})
Um caminho relativo é resolvido a partir do ficheiro Python que chama from_file, e não a partir do diretório de lançamento. O build aceita um dicionário ou um modelo Pydantic.
O que contém um modelo
O modelo é um modelo Jinja que produz o JSON do widget. O modelo do cartão de encomenda tem este aspeto:
ORDER_TEMPLATE = """
{
"type": "Card",
"children": [
{"type": "Row", "justify": "between", "align": "center", "children": [
{"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
{"type": "Badge", "label": {{ status | tojson }}, "color": {{ color | tojson }}}
]},
{"type": "Divider"},
{"type": "Col", "gap": 2, "children": [
{%- for item in items %}
{"type": "Row", "justify": "between", "children": [
{"type": "Text", "value": {{ item.name | tojson }}},
{"type": "Text", "value": {{ item.price | tojson }}}
]}{% if not loop.last %},{% endif %}
{%- endfor %}
]},
{"type": "Divider"},
{"type": "Row", "justify": "between", "children": [
{"type": "Text", "value": "Total", "weight": "semibold"},
{"type": "Text", "value": {{ total | tojson }}, "weight": "semibold"}
]}
]
}
"""
order_template = WidgetTemplate({"version": "1.0", "name": "order", "template": ORDER_TEMPLATE})
Raramente escreverá um modelo à mão, uma vez que o Widget Builder o gera. Mas ler um poupar-lhe-á tempo quando surgir o primeiro problema. Três observações:
- O filtro
tojsonconverte cada valor em JSON válido (uma cadeia entre aspas, um booleano comotrueoufalse) e escapa caracteres especiais: um apóstrofo ou aspas num nome de produto não quebrará o JSON. - O Jinja executa em modo estrito: dados em falta fazem com que o
buildfalhe, em vez de produzir um widget meio vazio. - O
buildnão valida os dados face aojsonSchema. Este esquema documenta os dados; se estes provierem de uma ferramenta ou de uma base de dados, valide-os previamente, por exemplo com um modelo Pydantic.
O construtor WidgetTemplate(...) aceita o mesmo conteúdo que um ficheiro .widget já lido: isto é útil para testes ou para um modelo gerado pelo seu próprio código.
Apresentação do widget a partir de respond
Para enviar o widget para o tópico, o stream_widget produz os eventos ChatKit correspondentes. Reencaminha-os a partir do seu método respond:
from chatkit.server import stream_widget
# Na sua classe ChatKitServer
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # os seus dados
async for event in stream_widget(
thread,
card,
copy_text="Order C-42: shipped, $59.90",
generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
):
yield event
O copy_text é o texto copiado para a área de transferência quando o utilizador clica no botão de cópia abaixo da resposta. O servidor guarda o widget na store propriamente dita, como qualquer elemento de difusão.
Deixar o agente decidir
Na maioria das vezes, não é o seu código que decide apresentar um cartão, mas o agente, quando a conversa o exige. Forneça-lhe uma ferramenta que difunda o widget com AgentContext.stream_widget: o stream_agent_response, visto na lição 17, transmite-o para a interface no meio da resposta.
from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext
@function_tool(description_override="Displays order details as a card.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
data = await get_order_data(number) # o seu acesso aos dados
await ctx.context.stream_widget(order_template.build(data))
return f"The card for order {number} is displayed."
Adicione a ferramenta à lista tools do agente. A cadeia devolvida pela ferramenta serve o modelo, que assim sabe que o cartão está no ecrã e pode comentá-lo em vez de o repetir.
Uma lista clicável
Para oferecer uma escolha, o ListView apresenta linhas clicáveis. Cada ListViewItem pode transportar uma ação, acionada ao clicar sem que o utilizador tenha de escrever nada; a próxima lição mostra como tratá-la do lado do servidor.
LIST_TEMPLATE = """
{
"type": "ListView",
"limit": 5,
"children": [
{%- for o in orders %}
{
"type": "ListViewItem",
"key": {{ o.number | tojson }},
"onClickAction": {"type": "order.open", "payload": {"number": {{ o.number | tojson }}}},
"children": [
{"type": "Col", "children": [
{"type": "Text", "value": {{ ("Order " ~ o.number) | tojson }},
{"type": "Caption", "value": {{ o.date | tojson }}}
]}
]
}{% if not loop.last %},{% endif %}
{%- endfor %}
]
}
"""
order_list_template = WidgetTemplate({"version": "1.0", "name": "order_list", "template": LIST_TEMPLATE})
list_widget = order_list_template.build({"orders": [{"number": "C-42", "date": "November 2"}, {"number": "C-41", "date": "October 28"}]})
Para além do limit, o ChatKit apresenta uma ligação «ver mais».
Atualização de um widget durante a exibição
Um widget pode evoluir perante os olhos do utilizador, por exemplo para apresentar um rascunho que o modelo está a escrever. Forneça ao stream_widget um gerador assíncrono que produza estados sucessivos do widget: o ChatKit calcula as diferenças e envia apenas o que muda.
from collections.abc import AsyncGenerator
from chatkit.widgets import DynamicWidgetRoot, WidgetTemplate
draft_template = WidgetTemplate({
"version": "1.0",
"name": "draft",
"template": """{"type": "Card", "children": [
{"type": "Title", "value": "Draft"},
{"type": "Text", "id": "body", "value": {{ text | tojson }}, "streaming": {{ in_progress | tojson }}}
]}""",
})
async def streaming_draft(chunks: AsyncGenerator[str, None]) -> AsyncGenerator[DynamicWidgetRoot, None]:
text = ""
async for chunk in chunks:
text += chunk
yield draft_template.build({"text": text, "in_progress": True})
# Estado final, uma vez que o texto esteja completo
yield draft_template.build({"text": text, "in_progress": False})
Apenas os componentes Text e Markdown com um id apresentam as suas atualizações num fluxo, palavra por palavra; para os outros, o ChatKit substitui a parte modificada do widget.
E as classes Python?
Encontrará, mesmo nos guias da OpenAI, widgets construídos com classes: Card(children=[Text(value="…")]). Ainda funcionam, mas o SDK openai-chatkit 1.6.5 declara-as obsoletas em favor do WidgetTemplate: utilizá-las emite um aviso que aponta para ficheiros .widget. Para um novo projeto, comece pelos modelos. Para um projeto existente, migre ao seu ritmo: o aviso não bloqueia nada, mas uma classe obsoleta pode desaparecer numa versão futura.
Quando utilizar um widget
A documentação cita utilizações típicas:
- recolher entrada estruturada com um formulário ou apresentar um resultado rico (tabela, cartão, gráfico) que o texto renderiza mal;
- oferecer uma escolha entre várias opções;
- combinar o widget com ações, para validar uma seleção, confirmar uma etapa ou lançar um processamento do lado do servidor;
- acompanhar um texto explicativo curto com um comando interativo.
Pelo contrário, não os coloque em toda a parte. Um widget que repete palavra por palavra o que o texto diz não acrescenta nada, e uma conversa saturada de cartões torna-se tão difícil de ler como uma parede de texto.
Pontos-chave
- Um widget do ChatKit é uma descrição declarativa (JSON) construída pelo seu servidor, não um componente React: o ChatKit renderiza-o ele próprio
- Três contentores:
Card(conteúdo autónomo),ListView(lista de opções),Basic(pré-visualizações de entidades) - Conceba no Widget Builder, exporte um ficheiro
.widget, carregue-o comWidgetTemplate.from_file(...)e preencha-o combuild(data); as classesCard,Text… estão obsoletas - Difunda com
stream_widgeta partir derespond, ou a partir de uma ferramenta do agente comctx.context.stream_widget - Um gerador assíncrono atualiza o widget em direto; apenas
TexteMarkdowncom umidtransmitem palavra por palavra