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

Integração avançada na sua aplicação

Aula 21 de 25 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O que falta após a demonstração
  2. Autenticar cada pedido
  3. Cada utilizador tem as suas próprias conversas
  4. Fornecer o contexto da sua aplicação ao modelo
  5. Ferramentas do lado do cliente
  6. Controlar o ChatKit a partir da sua aplicação
  7. Observar o que está a acontecer
  8. Antes de ir para produção
  9. Pontos-chave

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 Python openai-chatkit 1.6.5 (Prepare your app for production, Pass extra app context, Update the client during a response) e os tipos @openai/chatkit-react 1.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_context e 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étodoEfeito
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-Language orienta 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.fetch do lado da interface e, em seguida, via o contexto de server.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