feat: add thinking message events and types to enhance agent reasoning visibility

Author: DennySORA

docs/introduction.mdx

@@ -23,6 +23,8 @@ AG-UI provides:
   communication
 - **Best practices** for chat, streaming state updates, human-in-the-loop and
   shared state
+- **Thinking transparency** with dedicated thinking message events that expose
+  agent reasoning processes to users
 
 ## Existing Integrations
 

docs/quickstart/introduction.mdx

@@ -19,6 +19,7 @@ Think of it like adding a universal translator to your agent. Instead of buildin
 
 Agents integrating with AG-UI can:
 - **Stream responses** - Real-time text that appears as it's generated
+- **Show thinking** - Expose internal reasoning through thinking message events
 - **Call client-side tools** - Your agent can use functions and services defined by clients
 - **Share state** - Your agent's state is bidirectional shared state
 - **Execute universally** - Integrate with any AG-UI compatible client application

docs/sdk/python/core/events.mdx

@@ -22,6 +22,9 @@ class EventType(str, Enum):
     TEXT_MESSAGE_START = "TEXT_MESSAGE_START"
     TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT"
     TEXT_MESSAGE_END = "TEXT_MESSAGE_END"
+    THINKING_TEXT_MESSAGE_START = "THINKING_TEXT_MESSAGE_START"
+    THINKING_TEXT_MESSAGE_CONTENT = "THINKING_TEXT_MESSAGE_CONTENT"
+    THINKING_TEXT_MESSAGE_END = "THINKING_TEXT_MESSAGE_END"
     TOOL_CALL_START = "TOOL_CALL_START"
     TOOL_CALL_ARGS = "TOOL_CALL_ARGS"
     TOOL_CALL_END = "TOOL_CALL_END"
@@ -210,6 +213,64 @@ class TextMessageEndEvent(BaseEvent):
 | ------------ | ----- | ----------------------------------------- |
 | `message_id` | `str` | Matches the ID from TextMessageStartEvent |
 
+## Thinking Message Events
+
+These events represent the lifecycle of thinking messages that show an agent's internal reasoning process.
+
+### ThinkingTextMessageStartEvent
+
+`from ag_ui.core import ThinkingTextMessageStartEvent`
+
+Signals the start of a thinking message.
+
+```python
+class ThinkingTextMessageStartEvent(BaseEvent):
+    type: Literal[EventType.THINKING_TEXT_MESSAGE_START]
+    thinking_id: str
+```
+
+| Property      | Type  | Description                           |
+| ------------- | ----- | ------------------------------------- |
+| `thinking_id` | `str` | Unique identifier for the thinking sequence |
+
+### ThinkingTextMessageContentEvent
+
+`from ag_ui.core import ThinkingTextMessageContentEvent`
+
+Represents a chunk of content in a streaming thinking message.
+
+```python
+class ThinkingTextMessageContentEvent(BaseEvent):
+    type: Literal[EventType.THINKING_TEXT_MESSAGE_CONTENT]
+    thinking_id: str
+    delta: str  # Non-empty string
+
+    def model_post_init(self, __context):
+        if len(self.delta) == 0:
+            raise ValueError("Delta must not be an empty string")
+```
+
+| Property      | Type  | Description                                        |
+| ------------- | ----- | -------------------------------------------------- |
+| `thinking_id` | `str` | Matches the ID from ThinkingTextMessageStartEvent |
+| `delta`       | `str` | Thinking content chunk (non-empty)                |
+
+### ThinkingTextMessageEndEvent
+
+`from ag_ui.core import ThinkingTextMessageEndEvent`
+
+Signals the end of a thinking message.
+
+```python
+class ThinkingTextMessageEndEvent(BaseEvent):
+    type: Literal[EventType.THINKING_TEXT_MESSAGE_END]
+    thinking_id: str
+```
+
+| Property      | Type  | Description                                        |
+| ------------- | ----- | -------------------------------------------------- |
+| `thinking_id` | `str` | Matches the ID from ThinkingTextMessageStartEvent |
+
 ## Tool Call Events
 
 These events represent the lifecycle of tool calls made by agents.
@@ -392,6 +453,9 @@ Event = Annotated[
         TextMessageStartEvent,
         TextMessageContentEvent,
         TextMessageEndEvent,
+        ThinkingTextMessageStartEvent,
+        ThinkingTextMessageContentEvent,
+        ThinkingTextMessageEndEvent,
         ToolCallStartEvent,
         ToolCallArgsEvent,
         ToolCallEndEvent,

docs/sdk/python/core/types.mdx

@@ -51,7 +51,7 @@ messages in the system.
 Represents the possible roles a message sender can have.
 
 ```python
-Role = Literal["developer", "system", "assistant", "user", "tool"]
+Role = Literal["developer", "system", "assistant", "user", "tool", "thinking"]
 ```
 
 ### DeveloperMessage
@@ -155,6 +155,26 @@ class ToolMessage(ConfiguredBaseModel):
 | `tool_call_id` | `str`             | ID of the tool call this message responds to |
 | `error`        | `Optional[str]`   | Error message if the tool call failed        |
 
+### ThinkingMessage
+
+`from ag_ui.core import ThinkingMessage`
+
+Represents a thinking message that shows an agent's internal reasoning process.
+
+```python
+class ThinkingMessage(BaseMessage):
+    role: Literal["thinking"]
+    content: str
+```
+
+| Property    | Type                  | Description                                     |
+| ----------- | --------------------- | ----------------------------------------------- |
+| `id`        | `str`                 | Unique identifier for the message               |
+| `role`      | `Literal["thinking"]` | Role of the message sender, fixed as "thinking" |
+| `content`   | `str`                 | Text content of the thinking (required)         |
+| `name`      | `Optional[str]`       | Optional name of the sender                     |
+| `timestamp` | `Optional[int]`       | Optional timestamp for temporal tracking        |
+
 ### Message
 
 `from ag_ui.core import Message`
@@ -163,7 +183,7 @@ A union type representing any type of message in the system.
 
 ```python
 Message = Annotated[
-    Union[DeveloperMessage, SystemMessage, AssistantMessage, UserMessage, ToolMessage],
+    Union[DeveloperMessage, SystemMessage, AssistantMessage, UserMessage, ToolMessage, ThinkingMessage],
     Field(discriminator="role")
 ]
 ```