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

Widgets Interativos

Aula 19 de 25 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O que é um widget do ChatKit?
  2. Contentores e componentes
  3. Conceção do widget no Widget Builder
  4. O que contém um modelo
  5. Apresentação do widget a partir de respond
  6. Deixar o agente decidir
  7. Uma lista clicável
  8. Atualização de um widget durante a exibição
  9. E as classes Python?
  10. Quando utilizar um widget
  11. Pontos-chave

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 Python openai-chatkit 1.6.5, que constrói widgets a partir de modelos .widget: as suas classes Card, 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:

ContentorUtilização
CardConteú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
ListViewUm conjunto de opções: restaurantes, ficheiros, encomendas. Os seus filhos são ListViewItem, com funcionalidade integrada de «ver mais» (limit)
BasicReservado 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 tojson converte cada valor em JSON válido (uma cadeia entre aspas, um booleano como true ou false) 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 build falhe, em vez de produzir um widget meio vazio.
  • O build não valida os dados face ao jsonSchema. 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 com WidgetTemplate.from_file(...) e preencha-o com build(data); as classes Card, Text… estão obsoletas
  • Difunda com stream_widget a partir de respond, ou a partir de uma ferramenta do agente com ctx.context.stream_widget
  • Um gerador assíncrono atualiza o widget em direto; apenas Text e Markdown com um id transmitem palavra por palavra