openai/chatkit-python
Publicmirrored fromhttps://github.com/openai/chatkit-pythonAvailable
docs/concepts/thread-stream-events.md
46lines · modecode
| 1 | # Thread stream events |
| 2 | |
| 3 | [`ThreadStreamEvent`](../api/chatkit/types.md#chatkit.types.ThreadStreamEvent)s are the Server-Sent Event (SSE) payloads streamed by ChatKitServer while responding to a user message or action. They keep the client UI in sync with server-side processing and drive persistence in your store. |
| 4 | |
| 5 | ## Thread metadata updates |
| 6 | |
| 7 | ChatKitServer emits these after it creates a thread or notices metadata changes (title, status, etc.) so the UI stays in sync. |
| 8 | |
| 9 | - [`ThreadCreatedEvent`](../api/chatkit/types.md#chatkit.types.ThreadCreatedEvent): introduce a new thread |
| 10 | - [`ThreadUpdatedEvent`](../api/chatkit/types.md#chatkit.types.ThreadUpdatedEvent): update the current thread metadata such as title or status |
| 11 | |
| 12 | ## Thread item events |
| 13 | |
| 14 | Thread item events drive the conversation state. ChatKitServer processes these events to persist conversation state before streaming them back to the client. |
| 15 | |
| 16 | - [`ThreadItemAddedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemAddedEvent): introduce a new item (message, tool call, workflow, widget, etc). |
| 17 | - [`ThreadItemUpdatedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemUpdatedEvent): mutate a pending item (e.g., stream text deltas, workflow task updates). |
| 18 | - [`ThreadItemDoneEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemDoneEvent): mark an item complete and persist it. |
| 19 | - [`ThreadItemRemovedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemRemovedEvent): delete an item by id. |
| 20 | - [`ThreadItemReplacedEvent`](../api/chatkit/types.md#chatkit.types.ThreadItemReplacedEvent): swap an item in place. |
| 21 | |
| 22 | Note: `ThreadItemAddedEvent` does not persist the item. `ChatKitServer` saves on `ThreadItemDoneEvent`/`ThreadItemReplacedEvent`, tracks pending items in between, and handles store writes for all `ThreadItem*Event`s. |
| 23 | |
| 24 | ## Errors |
| 25 | |
| 26 | Stream [`ErrorEvent`](../api/chatkit/types.md#chatkit.types.ErrorEvent)s for user-facing errors in the chat UI. You can configure a custom message and whether a retry button is shown to the user. |
| 27 | |
| 28 | ## Progress updates |
| 29 | |
| 30 | Stream [`ProgressUpdateEvent`](../api/chatkit/types.md#chatkit.types.ProgressUpdateEvent)s to show the user transient status while work is in flight. |
| 31 | |
| 32 | See [Show progress while tools run](../guides/update-client-during-response.md#show-progress-while-tools-run) for more info. |
| 33 | |
| 34 | ## Client effects |
| 35 | |
| 36 | Use [`ClientEffectEvent`](../api/chatkit/types.md#chatkit.types.ClientEffectEvent) to trigger fire-and-forget behavior on the client such as opening a dialog or pushing updates. |
| 37 | |
| 38 | See [Trigger client-side effects without blocking](../guides/update-client-during-response.md#trigger-client-side-effects-without-blocking) for more info. |
| 39 | |
| 40 | ## Stream options |
| 41 | |
| 42 | [`StreamOptionsEvent`](../api/chatkit/types.md#chatkit.types.StreamOptionsEvent) configures runtime stream behavior (for example, allowing user cancellation). `ChatKitServer` emits one at the start of every stream using `get_stream_options`; override that method to change defaults such as `allow_cancel`. |
| 43 | |
| 44 | |
| 45 | ## Related guides |
| 46 | - [Respond to a user message](../guides/respond-to-user-message.md) |
| 47 | |