feat: add thinking message support in events and types in python. #370

[DennySORA]

Change Documentation: Thinking Message Support in Python SDK

Overview

This change adds comprehensive support for thinking messages in the AG-UI Python SDK, enhancing the protocol to handle internal reasoning processes of AI agents.

Files Modified

• python-sdk/ag_ui/core/events.py
• python-sdk/ag_ui/core/types.py

Changes Summary

1. Enhanced Thinking Message Events (events.py)

Added thinking_id Field

All thinking message events now include a thinking_id field for proper tracking and correlation:

• ThinkingTextMessageStartEvent: Added thinking_id: str field
• ThinkingTextMessageContentEvent: Added thinking_id: str field
• ThinkingTextMessageEndEvent: Added thinking_id: str field

This enables:

• Unique identification of thinking sequences
• Proper correlation between start, content, and end events
• Support for concurrent thinking processes

Cleanup

• Removed unused Role import from events.py

2. Enhanced Message Types (types.py)

New ThinkingMessage Class

class ThinkingMessage(BaseMessage):
    role: Literal["thinking"] = "thinking"
    content: str

Features:

• Dedicated message type for agent internal reasoning
• Required content field (thinking must have content)
• Fixed role as "thinking"

Enhanced BaseMessage

• Added timestamp field: Optional[int] = None for temporal tracking of messages

Updated Type Unions

• Message union: Now includes ThinkingMessage alongside existing message types
• Role literal: Extended to include "thinking" role

Technical Impact

Protocol Enhancement

• Thinking messages are now first-class citizens in the AG-UI protocol
• Proper event lifecycle management for thinking sequences
• Consistent with TypeScript SDK thinking message implementation

Developer Benefits

• Better Debugging: Thinking IDs enable tracing of reasoning processes
• Temporal Tracking: Optional timestamps for message ordering
• Type Safety: Proper typing for thinking messages prevents runtime errors

Backward Compatibility

• All changes are additive - existing code continues to work
• Optional timestamp field doesn't break existing message creation
• New thinking message type is optional to use

Usage Examples

Creating Thinking Messages

thinking_msg = ThinkingMessage(
    content="Let me think about this step by step...",
    timestamp=1694534400
)

Thinking Event Sequence

# Start thinking
start_event = ThinkingTextMessageStartEvent(thinking_id="think_001")

# Add content
content_event = ThinkingTextMessageContentEvent(
    delta="I need to consider...", 
    thinking_id="think_001"
)

# End thinking
end_event = ThinkingTextMessageEndEvent(thinking_id="think_001")

Related Issues

• Addresses issue Feature request: add field support #370
• Aligns Python SDK with TypeScript SDK thinking message capabilities
• Enhances agent transparency and debugging capabilities

Testing Considerations

• Verify thinking message serialization/deserialization
• Test thinking event lifecycle with proper ID correlation
• Validate timestamp handling for message ordering
• Ensure backward compatibility with existing message types

[vercel]

@DennySORA is attempting to deploy a commit to the CopilotKit Team on Vercel.

A member of the Team first needs to authorize it.

[tylerslaton]

Hi @DennySORA thanks for submitting this PR. I'm going to create a clone of this and run the tests against to ensure this is passing.