openai/chatkit-python
Publicmirrored from https://github.com/openai/chatkit-pythonAvailable
docs/concepts/thread-stream-events.md
46lines · modeblame
e14bb125Jiwon Kim6 months ago | 1 | # Thread stream events |
| 2 | | |
cce4d65fJiwon Kim6 months ago | 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. |
e14bb125Jiwon Kim6 months ago | 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 | | |
cce4d65fJiwon Kim6 months ago | 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 | |
e14bb125Jiwon Kim6 months ago | 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 | | |
cce4d65fJiwon Kim6 months ago | 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. | |
e14bb125Jiwon Kim6 months ago | 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 | | |
cce4d65fJiwon Kim6 months ago | 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. |
e14bb125Jiwon Kim6 months ago | 27 | |
| 28 | ## Progress updates | |
| 29 | | |
cce4d65fJiwon Kim6 months ago | 30 | Stream [`ProgressUpdateEvent`](../api/chatkit/types.md#chatkit.types.ProgressUpdateEvent)s to show the user transient status while work is in flight. |
e14bb125Jiwon Kim6 months ago | 31 | |
e8c87839Jiwon Kim6 months ago | 32 | See [Show progress while tools run](../guides/update-client-during-response.md#show-progress-while-tools-run) for more info. |
e14bb125Jiwon Kim6 months ago | 33 | |
| 34 | ## Client effects | |
| 35 | | |
cce4d65fJiwon Kim6 months ago | 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. |
e14bb125Jiwon Kim6 months ago | 37 | |
e8c87839Jiwon Kim6 months ago | 38 | See [Trigger client-side effects without blocking](../guides/update-client-during-response.md#trigger-client-side-effects-without-blocking) for more info. |
e14bb125Jiwon Kim6 months ago | 39 | |
| 40 | ## Stream options | |
| 41 | | |
cce4d65fJiwon Kim6 months ago | 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`. |
e14bb125Jiwon Kim6 months ago | 43 | |
| 44 | | |
| 45 | ## Related guides | |
e8c87839Jiwon Kim6 months ago | 46 | - [Respond to a user message](../guides/respond-to-user-message.md) |