Integraciones avanzadas con ChatKit

Si necesitas control total para personalizar la autenticación, cumplir requisitos de residencia de datos, desplegar el servicio en tus instalaciones u orquestar agentes a medida, puedes ejecutar ChatKit en tu propia infraestructura. La opción avanzada de alojamiento propio de OpenAI te permite usar tu propio servidor y personalizar ChatKit.

Ejecuta ChatKit en tu propia infraestructura

En términos generales, una integración avanzada de ChatKit consiste en crear tu propio servidor de ChatKit y agregar widgets para dar forma a la interfaz del chat. Usarás las API de OpenAI y tu servidor de ChatKit para crear un chat personalizado que utiliza modelos de OpenAI.

Configura tu servidor de ChatKit

Sigue la guía del servidor en GitHub para aprender a procesar solicitudes entrantes, ejecutar herramientas y transmitir los resultados al cliente a medida que se generan. Los siguientes fragmentos de código muestran los componentes principales.

1. Instala el paquete del servidor

pip install openai-chatkit

2. Implementa una clase de servidor

ChatKitServer gestiona la conversación. Sobrescribe respond para transmitir eventos cada vez que llegue un mensaje del usuario o el resultado de una herramienta del cliente. Funciones auxiliares como stream_agent_response conectan el servidor con el SDK de Agentes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27class MyChatKitServer(ChatKitServer[RequestContext]):
    async def respond(
        self,
        thread: ThreadMetadata,
        input: UserMessageItem | ClientToolCallOutputItem | None,
        context: RequestContext,
    ) -> AsyncIterator[Event]:
        items_page = await self.store.load_thread_items(
            thread.id,
            after=None,
            limit=20,
            order="desc",
            context=context,
        )
        input_items = await simple_to_agent_input(list(reversed(items_page.data)))
        agent_context = AgentContext(
            thread=thread,
            store=self.store,
            request_context=context,
        )
        result = Runner.run_streamed(
            assistant_agent,
            input_items,
            context=agent_context,
        )
        async for event in stream_agent_response(agent_context, result):
            yield event

3. Expón el punto de acceso

Usa el framework que prefieras para reenviar las solicitudes HTTP a la instancia del servidor. El siguiente ejemplo usa FastAPI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14from fastapi import FastAPI, Request, Response
from fastapi.responses import StreamingResponse

app = FastAPI()
data_store = MemoryStore()
server = MyChatKitServer(data_store)


@app.post("/chatkit")
async def chatkit_endpoint(request: Request):
    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")

4. Define el contrato de almacenamiento de datos

Implementa chatkit.store.Store para guardar hilos, mensajes y archivos en la base de datos que prefieras. Para el desarrollo local, puedes usar una implementación de Store en memoria. En producción, usa almacenamiento persistente y considera guardar los modelos como blobs JSON para que el esquema pueda evolucionar con las actualizaciones de la biblioteca sin necesidad de migraciones.

5. Implementa el contrato de almacenamiento de archivos

Proporciona una implementación de FileStore si tu aplicación admite cargas de archivos. ChatKit admite cargas directas (el cliente envía el archivo a tu punto de acceso mediante una solicitud POST) y cargas en dos fases (el cliente solicita una URL firmada y luego sube el archivo al almacenamiento en la nube). Proporciona vistas previas para mostrar miniaturas en el chat y gestiona la eliminación de los archivos cuando se eliminen los hilos correspondientes.

6. Invoca herramientas del cliente desde el servidor

Debes registrar las herramientas del cliente tanto en las opciones del cliente como en tu agente. Usa ctx.context.client_tool_call para poner en cola una llamada desde una herramienta del SDK de Agentes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15@function_tool(description_override="Add an item to the user's todo list.")
async def add_to_todo_list(ctx: RunContextWrapper[AgentContext], item: str) -> None:
    ctx.context.client_tool_call = ClientToolCall(
        name="add_to_todo_list",
        arguments={"item": item},
    )


assistant_agent = Agent[AgentContext](
    model="gpt-6-astra",
    name="Assistant",
    instructions="You are a helpful assistant",
    tools=[add_to_todo_list],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[add_to_todo_list.name]),
)

7. Usa los metadatos y el estado del hilo

Usa thread.metadata para guardar el estado del lado del servidor, como el ID de la ejecución anterior de la API de Responses o etiquetas personalizadas. El cliente no tiene acceso a los metadatos, pero están disponibles en cada llamada a respond.

8. Obtén actualizaciones del estado de las herramientas

Las herramientas de larga duración pueden transmitir su progreso a la interfaz mediante ProgressUpdateEvent. ChatKit reemplaza el evento de progreso por el siguiente mensaje del asistente o el resultado de un widget.

9. Uso del contexto del servidor

Pasa un objeto de contexto personalizado a server.process(body, context) para aplicar los permisos o propagar la identidad del usuario a través de tus implementaciones de almacenamiento de datos y archivos.

Agrega widgets interactivos dentro del chat

Los widgets permiten que los agentes muestren elementos de interfaz avanzados dentro del chat. Úsalos para mostrar tarjetas, formularios, bloques de texto, listas y otros diseños. La función auxiliar stream_widget puede mostrar un widget de inmediato o transmitir sus actualizaciones a medida que llegan.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22async def respond(
    self,
    thread: ThreadMetadata,
    input: UserMessageItem | ClientToolCallOutputItem | None,
    context: RequestContext,
) -> AsyncIterator[Event]:
    widget = Card(
        children=[
            Text(
                id="description",
                value="Generated summary",
            )
        ]
    )
    async for event in stream_widget(
        thread,
        widget,
        generate_id=lambda item_type: self.store.generate_item_id(
            item_type, thread, context
        ),
    ):
        yield event

ChatKit incluye una amplia variedad de nodos de widgets, como tarjetas, listas, formularios, texto y botones. Consulta la guía de widgets en GitHub para conocer todos los componentes y sus propiedades, así como las pautas para transmitir actualizaciones.

Visita Widget Builder para explorar y crear widgets en una interfaz interactiva.

Usa acciones

Las acciones permiten que la interfaz de ChatKit inicie tareas sin enviar un mensaje del usuario. Asocia una configuración ActionConfig a cualquier nodo de widget que la admita. Los botones, los selectores y otros controles pueden transmitir nuevos elementos del hilo o actualizar los widgets donde se muestran. Cuando un widget forma parte de un Form, ChatKit incluye los valores recopilados en el formulario en la carga útil de la acción.

En el servidor, implementa el método action de ChatKitServer para procesar la carga útil y, si lo deseas, transmitir eventos adicionales. También puedes gestionar las acciones en el cliente si configuras handler="client" y respondes en JavaScript antes de enviar las tareas posteriores al servidor.

Consulta la guía de acciones en GitHub para conocer patrones que permiten encadenar acciones, crear cargas útiles con tipado fuerte y coordinar los manejadores de acciones del cliente y del servidor.

Recursos

Usa los siguientes recursos y la documentación de referencia para completar la integración.

Recursos de diseño

• Descarga OpenAI Sans Variable.
• Duplica el archivo y personaliza los componentes para tu producto.

Referencia de eventos

ChatKit emite instancias de CustomEvent desde el componente web. Escucha los eventos del ciclo de vida y lee los datos de la carga útil en event.detail.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19chatkit.addEventListener("chatkit.error", (event) => {
  console.error(event.detail.error);
});

chatkit.addEventListener("chatkit.response.start", () => {
  console.log("Response started");
});

chatkit.addEventListener("chatkit.response.end", () => {
  console.log("Response ended");
});

chatkit.addEventListener("chatkit.thread.change", (event) => {
  console.log("Active thread:", event.detail.threadId);
});

chatkit.addEventListener("chatkit.log", (event) => {
  console.log(event.detail.name, event.detail.data);
});

Referencia de opciones