document chunk events

Author: mme

docs/concepts/events.mdx

@@ -237,18 +237,23 @@ automatic scrolling to ensure the full message is visible.
 
 ### TextMessageChunk
 
-A self-contained text message event that combines start, content, and end.
+Convenience event that expands to Start → Content → End automatically.
 
-The `TextMessageChunk` event provides a convenient way to send complete text messages 
-in a single event instead of the three-event sequence (start, content, end). This is 
-particularly useful for simple messages or when the entire content is available at once. 
-The event includes both the message metadata and content, making it more efficient for 
-non-streaming scenarios.
+The `TextMessageChunk` event lets you omit explicit `TextMessageStart` and
+`TextMessageEnd` events. The client stream transformer expands chunks into the
+standard triad:
+
+- First chunk for a message must include `messageId` and will emit
+  `TextMessageStart` (role defaults to `assistant` when not provided).
+- Each chunk with a `delta` emits a `TextMessageContent` for the current
+  `messageId`.
+- `TextMessageEnd` is emitted automatically when the stream switches to a new
+  message ID or when the stream completes.
 
 | Property    | Description                                                                           |
 | ----------- | ------------------------------------------------------------------------------------- |
-| `messageId` | Optional unique identifier for the message                                            |
-| `role`      | Optional role of the sender ("developer", "system", "assistant", "user", "tool")    |
+| `messageId` | Optional unique identifier for the message; required on the first chunk of a message  |
+| `role`      | Optional role of the sender ("developer", "system", "assistant", "user")              |
 | `delta`     | Optional text content of the message                                                  |
 
 ## Tool Call Events
@@ -359,6 +364,28 @@ the tool's output.
 | `content`    | The actual result/output content from the tool execution    |
 | `role`       | Optional role identifier, typically "tool" for tool results |
 
+### ToolCallChunk
+
+Convenience event that expands to Start → Args → End automatically.
+
+The `ToolCallChunk` event lets you omit explicit `ToolCallStart` and
+`ToolCallEnd` events. The client stream transformer expands chunks into the
+standard tool-call triad:
+
+- First chunk for a tool call must include `toolCallId` and `toolCallName` and
+  will emit `ToolCallStart` (propagating any `parentMessageId`).
+- Each chunk with a `delta` emits a `ToolCallArgs` for the current
+  `toolCallId`.
+- `ToolCallEnd` is emitted automatically when the stream switches to a new
+  `toolCallId` or when the stream completes.
+
+| Property          | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `toolCallId`      | Optional on later chunks; required on the first chunk of a tool call        |
+| `toolCallName`    | Optional on later chunks; required on the first chunk of a tool call        |
+| `parentMessageId` | Optional ID of the parent message                                           |
+| `delta`           | Optional argument data chunk (often a JSON fragment)                        |
+
 ## State Management Events
 
 These events are used to manage and synchronize the agent's state with the

docs/sdk/js/core/events.mdx

@@ -201,6 +201,29 @@ type TextMessageEndEvent = BaseEvent & {
 | ----------- | -------- | ----------------------------------------- |
 | `messageId` | `string` | Matches the ID from TextMessageStartEvent |
 
+### TextMessageChunkEvent
+
+Convenience event that expands to `TextMessageStart` → `TextMessageContent` →
+`TextMessageEnd` automatically in the JS/TS client.
+
+```typescript
+type TextMessageChunkEvent = BaseEvent & {
+  type: EventType.TEXT_MESSAGE_CHUNK
+  messageId?: string // required on the first chunk for a message
+  role?: 'developer' | 'system' | 'assistant' | 'user'
+  delta?: string
+}
+```
+
+Behavior
+- Omit start/end: The client transforms chunk sequences into the standard
+  start/content/end triad, so you don’t need to emit them manually.
+- First chunk requirements: The first chunk for a message must include
+  `messageId`. When `role` is omitted, it defaults to `assistant`.
+- Streaming: Subsequent chunks with the same `messageId` emit
+  `TextMessageContent` events. `TextMessageEnd` is emitted automatically when a
+  different message starts or when the stream completes.
+
 ## Tool Call Events
 
 These events represent the lifecycle of tool calls made by agents.
@@ -430,3 +453,26 @@ const EventSchemas = z.discriminatedUnion("type", [
 
 This allows for runtime validation of events and provides TypeScript type
 inference.
+### ToolCallChunkEvent
+
+Convenience event that expands to `ToolCallStart` → `ToolCallArgs` →
+`ToolCallEnd` automatically in the JS/TS client.
+
+```typescript
+type ToolCallChunkEvent = BaseEvent & {
+  type: EventType.TOOL_CALL_CHUNK
+  toolCallId?: string // required on the first chunk for a tool call
+  toolCallName?: string // required on the first chunk for a tool call
+  parentMessageId?: string
+  delta?: string
+}
+```
+
+Behavior
+- Omit start/end: The client transforms chunk sequences into the standard
+  start/args/end triad.
+- First chunk requirements: The first chunk must include both `toolCallId` and
+  `toolCallName`; `parentMessageId` is propagated to `ToolCallStart` if given.
+- Streaming: Subsequent chunks with the same `toolCallId` emit `ToolCallArgs`.
+  `ToolCallEnd` is emitted automatically when the tool call changes or when the
+  stream completes.

docs/sdk/python/core/events.mdx

@@ -461,3 +461,50 @@ Event = Annotated[
 
 This allows for runtime validation of events and type checking at development
 time.
+### TextMessageChunkEvent
+
+Convenience event for complete text messages without manually emitting
+`TextMessageStart`/`TextMessageEnd`.
+
+```python
+from ag_ui.core import TextMessageChunkEvent
+
+class TextMessageChunkEvent(BaseEvent):
+    type: Literal[EventType.TEXT_MESSAGE_CHUNK]
+    message_id: Optional[str] = None  # required on first chunk for a message
+    role: Optional[TextMessageRole] = None  # defaults to "assistant" in JS client
+    delta: Optional[str] = None
+```
+
+Behavior
+- Convenience: Some consumers (e.g., the JS/TS client) expand chunk events into
+  the standard start/content/end sequence automatically, allowing producers to
+  omit explicit start/end events when using chunks.
+- First chunk requirements: The first chunk for a given message must include
+  `message_id`.
+- Streaming: Subsequent chunks with the same `message_id` correspond to content
+  pieces; completion triggers an implied end in clients that perform expansion.
+
+### ToolCallChunkEvent
+
+Convenience event for tool calls without manually emitting
+`ToolCallStart`/`ToolCallEnd`.
+
+```python
+from ag_ui.core import ToolCallChunkEvent
+
+class ToolCallChunkEvent(BaseEvent):
+    type: Literal[EventType.TOOL_CALL_CHUNK]
+    tool_call_id: Optional[str] = None      # required on first chunk
+    tool_call_name: Optional[str] = None    # required on first chunk
+    parent_message_id: Optional[str] = None
+    delta: Optional[str] = None
+```
+
+Behavior
+- Convenience: Consumers may expand chunk sequences into the standard
+  start/args/end triad (the JS/TS client does this automatically).
+- First chunk requirements: Include both `tool_call_id` and `tool_call_name` on
+  the first chunk.
+- Streaming: Subsequent chunks with the same `tool_call_id` correspond to args
+  pieces; completion triggers an implied end in clients that perform expansion.