ChatKit: Visão geral e instalação
Nesta página
Lição reescrita a 3 de novembro de 2026. A versão anterior descrevia uma API que já não existe: um objeto
new ChatKit({ apiKey, agentId }), os componentesChatProvider,ChatWindoweMessageInput, um módulo@openai/chatkit/reacte um scriptcdn.openai.com/chatkit/…. Esta lição segue agora os guias oficiais do ChatKit da OpenAI, o SDK Pythonopenai-chatkit1.6.5 e o@openai/chatkit-react1.6.1. Executámos o servidor de exemplo localmente para verificar cada passo. Nota: O Agent Builder será desativado a 30 de novembro de 2026; o ChatKit permanece disponível. Fontes: ChatKit · Integrações avançadas com ChatKit · Início rápido do SDK Python · Aplicação inicial oficial.
Porquê o ChatKit
Já criou um agente com o Agents SDK. Ele funciona no seu terminal e mais ninguém o pode utilizar. Para o colocar nas mãos dos seus utilizadores, precisa de uma interface de conversação — e criar uma boa interface de chat do zero é dispendioso. Tem de gerir a rolagem, a transmissão de mensagens em tempo real, a retoma da conversação, anexos, a visualização de chamadas de ferramentas e o tratamento de erros de rede.
O ChatKit é a resposta da OpenAI: um componente de conversação que incorpora no seu produto e que gere toda a experiência do utilizador. A documentação destaca os seus widgets interativos, sugestões iniciais, visualização de chamadas de ferramentas, anexos e a visualização do raciocínio do agente. Mantém o controlo sobre o que importa: o agente, os seus dados e as suas regras.
Duas formas de o alimentar
O ChatKit é apenas uma interface. Precisa de um servidor que receba mensagens, execute o agente e transmita a resposta de volta. A OpenAI descreve duas abordagens:
| Caminho | Como funciona | Para quem é |
|---|---|---|
| O seu próprio servidor ChatKit (integração avançada) | O seu servidor Python, utilizando o SDK openai-chatkit, recebe pedidos da interface e executa o agente da sua escolha, como um agente do Agents SDK | Qualquer novo projeto: este é o caminho recomendado pela OpenAI |
| Fluxo de trabalho do Agent Builder alojado | A OpenAI executa um fluxo de trabalho concebido no Agent Builder; o seu servidor apenas cria sessões | Integrações existentes durante o período de transição: o Agent Builder será desativado a 30 de novembro de 2026 |
Este curso segue o primeiro caminho — o único com futuro. Resumimos o segundo no final da lição para quem precise de manter uma integração existente até à desativação.
A arquitetura de três peças
Uma integração ChatKit resume-se a três elementos. Distingui-los evita a maioria dos erros de iniciante:
- ChatKit.js, o próprio componente: um componente web
<openai-chatkit>que exibe a conversação num iframe. É carregado a partir da CDN da OpenAI (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), não do npm: o pacote npm@openai/chatkitcontém apenas as suas definições de tipo. - Ligações React,
@openai/chatkit-react, que expõem o componenteChatKite o hookuseChatKit. São opcionais: sem React, controla o componente web diretamente. - O seu servidor ChatKit, um único endpoint HTTP, convencionalmente
/chatkit, que recebe todos os pedidos da interface. Uma instânciaChatKitServerencaminha-os, recorre a um armazenamento (store) para persistir os tópicos de conversação e executa o seu agente.
A chave de API da OpenAI nunca sai do servidor: a interface comunica apenas com o seu endpoint /chatkit.
Instalação
Do lado da interface, instale as ligações React e carregue o script ChatKit na sua página:
npm install @openai/chatkit-react
<!-- No <head> da sua página -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Do lado do servidor, instale o SDK Python do ChatKit (Python 3.10 ou posterior), que inclui o Agents SDK, além de um servidor web:
pip install openai-chatkit fastapi uvicorn
O servidor mínimo
O servidor abaixo segue o início rápido oficial. O ChatKitServer requer apenas um método, respond, chamado para cada mensagem do utilizador. Recarrega os últimos itens do tópico, converte-os em entrada para o agente com simple_to_agent_input, executa o agente em modo de transmissão e traduz esse fluxo em eventos ChatKit com stream_agent_response:
# main.py
from typing import Any, AsyncIterator
from agents import Agent, Runner
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse
from memory_store import MemoryStore # armazenamento em memória da aplicação inicial
assistant = Agent[AgentContext[dict[str, Any]]](
name="Product Assistant",
instructions="You help product users. Respond in English, briefly.",
model="gpt-6.1-sol",
)
class MyChatKitServer(ChatKitServer[dict[str, Any]]):
async def respond(
self,
thread: ThreadMetadata,
input_user_message: UserMessageItem | None,
context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
# Os últimos 30 itens do tópico, restaurados por ordem cronológica
page = await self.store.load_thread_items(
thread.id, after=None, limit=30, order="desc", context=context
)
agent_input = await simple_to_agent_input(list(reversed(page.data)))
agent_context = AgentContext(thread=thread, store=self.store, request_context=context)
result = Runner.run_streamed(assistant, agent_input, context=agent_context)
async for event in stream_agent_response(agent_context, result):
yield event
app = FastAPI()
server = MyChatKitServer(MemoryStore())
@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
result = await server.process(await request.body(), {})
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")
Execute-o com OPENAI_API_KEY no seu ambiente: uvicorn main:app --port 8000.
O armazenamento (store) merece duas palavras. O ChatKit não armazena nada por si próprio: tópicos, mensagens, widgets e chamadas de ferramentas são persistidos por uma classe que herda de chatkit.store.Store e implementa cerca de uma dúzia de métodos (load_thread, save_thread, load_thread_items, add_thread_item…). Para começar, reutilize o ficheiro memory_store.py da aplicação inicial oficial: mantém tudo na memória enquanto o processo estiver em execução. Em produção, substitua-o por uma base de dados. A documentação recomenda armazenar objetos como JSON para que as atualizações do SDK não o forcem a fazer migrações de esquema.
A interface React
Do lado da interface, useChatKit recebe a configuração e devolve um objeto control, que passa ao componente ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Em desenvolvimento, um valor de marcador é suficiente; em produção,
// utilize a sua chave de domínio (ver abaixo)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Sirva a interface e /chatkit a partir da mesma origem: em desenvolvimento, o proxy da sua ferramenta de compilação trata disso (a aplicação inicial configura o proxy do Vite para redirecionar /chatkit para a porta 8000). Se o servidor estiver numa origem diferente, permita-o explicitamente, por exemplo com o CORSMiddleware do FastAPI.
Sem React
Um site WordPress, uma aplicação Rails ou uma página estática podem integrar o mesmo assistente: o componente web funciona diretamente assim que o script da CDN é carregado.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
</head>
<body>
<div id="chat-root" style="height: 600px"></div>
<script>
const chatkit = document.createElement('openai-chatkit');
chatkit.setOptions({
api: { url: '/chatkit', domainKey: 'local-dev' },
});
document.getElementById('chat-root').append(chatkit);
</script>
</body>
</html>
Todas as opções que verá nas lições seguintes têm a mesma forma em ambos os casos: um objeto passado a useChatKit em React, ou a setOptions no componente web.
Segurança desde o primeiro dia
Três regras, retiradas do guia de produção do ChatKit, aplicam-se desde a fase de protótipo:
- A chave de API permanece no servidor. Não deve aparecer no código da interface nem no seu repositório: leia-a a partir de uma variável de ambiente ou de um gestor de segredos.
- Autentique todos os pedidos para
/chatkit. O SDK não trata disto: a sua aplicação deve verificar a sessão ou o token do utilizador e, em seguida, passar a sua identidade paraserver.processno contexto (lição 21). Sem isto, qualquer pessoa pode executar o seu agente às suas custas. - Registe os seus domínios. Antes de entrar em produção, declare cada nome de anfitrião que exibirá o ChatKit na página Lista de permissões de domínio da plataforma da OpenAI e copie a chave gerada para
domainKey. Ao carregar, o iframe do ChatKit verifica esta chave com a OpenAI e recusa-se a ser exibido se esta estiver em falta ou não corresponder.
Se já tiver um fluxo de trabalho do Agent Builder
As integrações existentes ligadas a um fluxo de trabalho alojado funcionam até o Agent Builder ser desativado. O seu princípio difere: o seu servidor cria uma sessão ChatKit chamando POST https://api.openai.com/v1/chatkit/sessions, com o cabeçalho OpenAI-Beta: chatkit_beta=v1, o ID do fluxo de trabalho e um identificador user único para cada utilizador autenticado. Devolve então o client_secret obtido à interface. Do lado da interface, a opção api recebe então uma função getClientSecret em vez de um URL.
Não inicie um novo projeto com este modelo. Para uma integração existente, exporte o fluxo de trabalho para código do Agents SDK e mude para o seu próprio servidor ChatKit antes de 30 de novembro de 2026, seguindo o guia Migrar do Agent Builder.
Pontos-chave
- O ChatKit é uma interface de conversação pronta a integrar; o seu servidor executa o agente
- Para qualquer novo projeto: o seu próprio servidor ChatKit (
pip install openai-chatkit), com um métodoresponde um endpoint/chatkit; o Agent Builder alojado será desativado a 30 de novembro de 2026 - A interface é carregada a partir da CDN da OpenAI; em React, utilize
useChatKite<ChatKit control={control} />de@openai/chatkit-react - O armazenamento (store) persiste os tópicos de conversação: na memória para testes, numa base de dados para produção
- Chave de API apenas no lado do servidor,
/chatkitautenticado, domínios registados para obter odomainKey