Integração avançada na sua aplicação
Nesta página
Lição reescrita em 3 de novembro de 2026. A versão anterior baseava-se em propriedades e eventos inventados (
ChatProvider, modo “sidebar”, persistência baseada em UI). Agora segue os guias do SDK Pythonopenai-chatkit1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) e os tipos@openai/chatkit-react1.6.1: o código do servidor foi executado localmente e o código React verificado por compilação. Fontes: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.
O que falta após a demonstração
As quatro lições anteriores fornecem-lhe um assistente funcional. Para o tornar operativo num produto real, precisa do que separa uma demonstração de um serviço: saber quem está a falar, mostrar a cada utilizador apenas as suas conversas, interagir com o resto da aplicação e ser observável. Esta lição aborda estes pontos um por um.
Autenticar cada pedido
O SDK não faz suposições sobre a sua autenticação: permite-lhe verificar o utilizador e, em seguida, passar a sua identidade para server.process num contexto de pedido. Este contexto acompanha todas as chamadas: encontra-o em respond, em action, no store e nas ferramentas do agente.
Do lado da interface, a opção api.fetch substitui a função fetch utilizada pelo ChatKit. É aqui que adiciona o token de sessão da sua aplicação:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function ConnectedAssistant({ obtainToken }: { obtainToken: () => Promise<string> }) {
const { control } = useChatKit({
api: {
url: '/chatkit',
domainKey: 'local-dev',
fetch: async (input, init) => {
// Manter os cabeçalhos definidos pelo ChatKit e adicionar os nossos
const headers = new Headers(init?.headers);
headers.set('Authorization', `Bearer ${await obtainToken()}`);
return fetch(input, { ...init, headers });
},
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Do lado do servidor, uma dependência FastAPI verifica o token e constrói o contexto. O idioma da interface chega no cabeçalho Accept-Language, que o ChatKit envia com cada pedido:
from dataclasses import dataclass
from chatkit.server import StreamingResult
from chatkit.store import NotFoundError
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import Response, StreamingResponse
@dataclass
class RequestContext:
user_id: str
locale: str
async def current_user(request: Request) -> str:
token = request.headers.get("authorization", "").removeprefix("Bearer ")
user_id = await verify_token(token) # a sua autenticação: sessão, JWT...
if not user_id:
raise HTTPException(status_code=401, detail="Unauthenticated")
return user_id
app = FastAPI()
@app.post("/chatkit")
async def chatkit_endpoint(request: Request, user_id: str = Depends(current_user)) -> Response:
context = RequestContext(user_id=user_id, locale=request.headers.get("accept-language", "fr"))
try:
result = await server.process(await request.body(), context)
except NotFoundError:
raise HTTPException(status_code=404, detail="Not found")
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")
Cada utilizador tem as suas próprias conversas
A autenticação não é suficiente: precisa também de autorização. Sem controlo, um utilizador que adivinhe um ID de thread poderia ler a conversa de outra pessoa. O local correto para este controlo é o store, por onde passam todas as leituras. Neste exemplo, cada thread mantém o nome do seu proprietário nos metadados, que o SDK nunca transmite à interface:
from chatkit.store import NotFoundError
from chatkit.types import Page, ThreadMetadata
from memory_store import MemoryStore
class UserStore(MemoryStore):
async def save_thread(self, thread: ThreadMetadata, context: RequestContext) -> None:
thread.metadata.setdefault("owner", context.user_id)
await super().save_thread(thread, context)
async def load_thread(self, thread_id: str, context: RequestContext) -> ThreadMetadata:
thread = await super().load_thread(thread_id, context)
if thread.metadata.get("owner") != context.user_id:
raise NotFoundError(f"Thread {thread_id} not found") # não revelar que existe
return thread
async def load_threads(self, limit, after, order, context: RequestContext) -> Page[ThreadMetadata]:
page = await super().load_threads(limit, after, order, context)
page.data = [t for t in page.data if t.metadata.get("owner") == context.user_id]
return page
O bloco try no endpoint faz sentido aqui: sem ele, ler diretamente a thread de outro utilizador resultaria num erro 500 em vez de um 404; num pedido em streaming, como adicionar uma mensagem, o SDK interrompe o fluxo sem enviar nada. Em produção, esta filtragem ocorre na própria consulta SQL (um WHERE owner = … também gere corretamente a paginação). Aplique a mesma regra aos anexos. A documentação lembra também que deve decidir o que guarda e por quanto tempo: as threads contêm texto, ficheiros e resultados de ferramentas, sendo frequentemente dados pessoais.
Fornecer o contexto da sua aplicação ao modelo
O modelo não sabe nada sobre a página que o utilizador está a visualizar, a sua subscrição ou o documento aberto. A documentação propõe três formas de o ensinar:
- Em cada pedido, através de cabeçalhos adicionados em
api.fetch(X-Page,X-Plan…), que o servidor armazena no contexto; - A pedido, através de uma ferramenta do servidor que lê
ctx.context.request_contexte obtém a informação; - No navegador, através de uma ferramenta do lado do cliente, quando a informação existe apenas aí (veja a secção seguinte).
Uma precaução, retirada do guia de produção: nunca construa as instruções de sistema do modelo a partir de valores que venham do utilizador, mesmo indiretamente (título da thread, assunto do ticket). Mantenha-as fixas e passe o contexto variável como dados.
Ferramentas do lado do cliente
Alguma informação vive apenas no navegador: seleção num editor, estado da tela, um rascunho não guardado. Uma ferramenta do lado do cliente permite ao modelo solicitá-las a meio da interação: o seu servidor pausa o agente, o ChatKit executa a sua função no navegador e devolve o resultado ao servidor, que retoma o processo.
Do lado do servidor, a ferramenta apenas faz o pedido e o agente para nela:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Reads the text the user has selected on the page.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})
assistant = Agent[AgentContext](
name="Writing Assistant",
instructions="Help the user improve the text they select.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
Do lado da interface, onClientTool recebe o pedido; o nome deve corresponder e o objeto devolvido vai para o servidor:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Apenas uma ferramenta do lado do cliente pode ser executada por turno. E quando não espera uma resposta, prefira um efeito: o servidor emite um ClientEffectEvent(name="refresh_cart", data={...}), a partir de respond, action ou de uma ferramenta via ctx.context.stream(...), e a interface recebe-o em onEffect sem interromper a resposta. Os efeitos não são registados na thread.
Controlar o ChatKit a partir da sua aplicação
useChatKit devolve, além de control, métodos para comandar a interface a partir do resto do seu código:
| Método | Efeito |
|---|---|
sendUserMessage({ text }) | Envia uma mensagem como se o utilizador a tivesse escrito |
setComposerValue({ text }) | Pré-preenche a área de entrada sem enviar |
setThreadId(id) | Abre uma thread existente ou uma nova thread com null |
focusComposer() | Coloca o cursor na área de entrada |
showHistory(), hideHistory() | Abre ou fecha o histórico de conversas |
sendCustomAction(action) | Envia uma ação para o servidor (Lição 20) |
fetchUpdates() | Recarrega a thread a partir do servidor |
Um botão “Perguntar ao assistente” numa ficha de produto torna-se numa linha de código:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function ProductSheet({ product }: { product: string }) {
const chatkit = useChatKit({ api: { url: '/chatkit', domainKey: 'local-dev' } });
return (
<>
<button onClick={() => chatkit.sendUserMessage({ text: `Is the ${product} product compatible with my equipment?` })}>
Ask the assistant
</button>
<ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
</>
);
}
A opção initialThread abre uma thread específica na montagem, por exemplo, aquela que o utilizador deixou aberta; com null (o valor predefinido), o ChatKit apresenta o ecrã inicial.
Observar o que está a acontecer
O ChatKit emite eventos: pronto (onReady), início e fim da resposta (onResponseStart, onResponseEnd), alteração de thread (onThreadChange), registos (onLog) e erros (onError). No React, estas são opções para useChatKit:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onThreadChange: ({ threadId }) => rememberLastThread(threadId),
onError: ({ error }) => sendTelemetry({ name: 'chatkit.error', message: error.message }),
onLog: ({ name }) => sendTelemetry({ name: name }),
});
O guia de produção insiste num ponto: estes eventos podem conter dados pessoais e texto de mensagens. Não envie todo o conteúdo para a sua ferramenta de rastreio: extraia apenas os campos úteis (nome do evento, ID da thread, código de erro). Do lado do servidor, registe cada pedido para /chatkit, chamadas ao store e ao modelo, e erros de ferramentas, com o ID do utilizador e da thread, para poder correlacionar ambos os lados.
Para ferramentas lentas, mantenha o utilizador informado: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) apresenta um progresso imediato, substituído pelo resto da resposta e nunca registado na thread.
Antes de ir para produção
A lista de verificação, retirada do guia oficial:
- Domínios: cada nome de anfitrião de produção está listado na página Domain allowlist da plataforma OpenAI e a sua chave está em
domainKey; - Autenticação e autorização: cada pedido para
/chatkité autenticado, threads e anexos são filtrados por utilizador; - Segredos: a chave da API e as credenciais internas estão em variáveis de ambiente ou num gestor de segredos, nunca no repositório;
- Entradas: mensagens, ficheiros, cargas de ações e resultados de ferramentas são tratados como não confiáveis e validados antes de chegarem aos seus sistemas;
- Dados pessoais: período de retenção decidido e aplicado no store, encriptação em repouso, sem dados desnecessários nos metadados;
- Idioma: o idioma
Accept-Languageorienta as respostas do agente e as mensagens das suas ferramentas; - Rastreio: eventos da interface e registos do servidor recolhidos, sem conteúdo sensível.
Pontos-chave
- A identidade do utilizador passa via
api.fetchdo lado da interface e, em seguida, via o contexto deserver.process, que a propaga para todo o lado - A autorização ocorre no store: cada thread pertence a um utilizador e a thread de outro utilizador é considerada “não encontrada”
- O contexto da aplicação chega via cabeçalhos, ferramentas do servidor ou ferramentas do lado do cliente (
onClientTool+StopAtTools); os efeitos (onEffect) servem quando não se espera resposta - Os métodos de
useChatKit(sendUserMessage,setThreadId,setComposerValue…) comandam o ChatKit a partir do resto da aplicação - Os eventos (
onError,onLog…) alimentam o seu rastreio, sem copiar dados pessoais para ele; a lista de verificação de produção abrange domínios, direitos, segredos, entradas e dados