Feature/claude agent sdk integration

[y-cruce]

Fixes #439

Add Claude Agent SDK Integration

Summary

This PR adds comprehensive integration support for Anthropic's Claude Agent SDK with the AG-UI Protocol, enabling Claude agents to seamlessly work within AG-UI applications. The integration includes both Python and TypeScript implementations, providing a complete bridge between Claude Agent SDK and the AG-UI Protocol.

Related Issue

Closes #439

Changes

Python Integration (integrations/claude-agent-sdk/python/)

• Core Components:

  • ClaudeAgent: Main orchestrator managing agent lifecycle and session state
  • EventTranslator: Converts Claude SDK responses to AG-UI protocol events (16 standard event types)
  • SessionManager: Singleton pattern for centralized session control with automatic cleanup
  • ToolAdapter: Handles tool format conversion between AG-UI and Claude SDK formats
  • ExecutionState: Tracks background Claude executions with event queue management

• Features:

  • ✅ Full AG-UI Protocol support with all standard event types
  • ✅ Persistent session management with configurable timeouts
  • ✅ Stateless mode support using query() method
  • ✅ Tool integration (client-side and backend tools)
  • ✅ Streaming responses with real-time event streaming
  • ✅ Thread-safe execution with isolated execution states
  • ✅ Comprehensive error handling and timeout management

• Testing:

  • Unit tests for all core components
  • Integration tests for basic functionality, sessions, and tools
  • Example FastAPI server implementation

TypeScript Integration (integrations/claude-agent-sdk/typescript/)

• Core Components:

  • ClaudeAgent: Extends AbstractAgent with Claude SDK integration
  • EventTranslator: Converts Claude SDK messages to AG-UI events
  • SessionManager: Manages persistent sessions with automatic cleanup
  • ToolAdapter: Handles tool format conversion
  • ExecutionState: Manages async execution state and event queues

• Features:

  • ✅ Full AG-UI Protocol support
  • ✅ Observable API using RxJS for event streams
  • ✅ Persistent and stateless session modes
  • ✅ Tool integration with MCP server support
  • ✅ TypeScript type definitions
  • ✅ Automatic session cleanup

• Testing:

  • Comprehensive test suite with Jest
  • Integration tests for various scenarios
  • Example implementations including CopilotKit integration

Architecture

The integration follows a clean architecture pattern:

AG-UI Protocol → Claude Middleware → Claude Agent SDK
     │                  │                    │
RunAgentInput ──> ClaudeAgent.run() ──> SDK Client/Query
     │                  │                    │
     │          EventTranslator              │
     │                  │                    │
BaseEvent[] <── translate events <── Response[]

Key Design Decisions

1. Session Management: Supports both persistent sessions (using ClaudeSDKClient) and stateless mode (using query() method)
2. Event Translation: Per-execution instances of EventTranslator ensure thread safety
3. Tool Handling: Distinguishes between client-side (long-running) and backend (synchronous) tools
4. Error Handling: Comprehensive error handling with RunErrorEvent for various failure scenarios
5. Performance: Async/await throughout for non-blocking operations with configurable concurrent execution limits

Testing

• ✅ Python: Comprehensive test suite with pytest
• ✅ TypeScript: Full test coverage with Jest
• ✅ Integration examples provided for both implementations
• ✅ Example servers demonstrating usage patterns

Documentation

• ✅ Python README with quick start guide
• ✅ TypeScript README with usage examples
• ✅ Architecture documentation explaining design decisions
• ✅ Example implementations for common use cases

Breaking Changes

None - This is a new integration addition.

Checklist

• Code follows the project's style guidelines
• Tests have been added/updated
• Documentation has been updated
• All tests pass
• No breaking changes introduced

[NathanTarbert]

Hey @y-cruce, I see there are a lot of tests, but did you test this fully against the dojo and add the SDK to the dojo?