The Qwen Code Java SDK is a minimum experimental SDK for programmatic access to Qwen Code functionality. It provides a Java interface to interact with the Qwen Code CLI, allowing developers to integrate Qwen Code capabilities into their Java applications.
other examples see src/test/java/com/alibaba/qwen/code/cli/example
## Architecture
The SDK follows a layered architecture:
- **API Layer**: Provides the main entry points through `QwenCodeCli` class with simple static methods for basic usage
- **Session Layer**: Manages communication sessions with the Qwen Code CLI through the `Session` class
- **Transport Layer**: Handles the communication mechanism between the SDK and CLI process (currently using process transport via `ProcessTransport`)
- **Protocol Layer**: Defines data structures for communication based on the CLI protocol
- **Utils**: Common utilities for concurrent execution, timeout handling, and error management
## Key Features
### Permission Modes
The SDK supports different permission modes for controlling tool execution:
- **`default`**: Write tools are denied unless approved via `canUseTool` callback or in `allowedTools`. Read-only tools execute without confirmation.
- **`plan`**: Blocks all write tools, instructing AI to present a plan first.
- **`auto-edit`**: Auto-approve edit tools (edit, write_file) while other tools require confirmation.
- **`yolo`**: All tools execute automatically without confirmation.
### Session Event Consumers and Assistant Content Consumers
The SDK provides two key interfaces for handling events and content from the CLI:
#### SessionEventConsumers Interface
The `SessionEventConsumers` interface provides callbacks for different types of messages during a session:
-`onSystemMessage`: Handles system messages from the CLI (receives Session and SDKSystemMessage)
-`onResultMessage`: Handles result messages from the CLI (receives Session and SDKResultMessage)
-`onAssistantMessage`: Handles assistant messages (AI responses) (receives Session and SDKAssistantMessage)
-`onPartialAssistantMessage`: Handles partial assistant messages during streaming (receives Session and SDKPartialAssistantMessage)
-`onUserMessage`: Handles user messages (receives Session and SDKUserMessage)
-`onOtherMessage`: Handles other types of messages (receives Session and String message)
-`onControlResponse`: Handles control responses (receives Session and CLIControlResponse)
-`onControlRequest`: Handles control requests (receives Session and CLIControlRequest, returns CLIControlResponse)
-`onPermissionRequest`: Handles permission requests (receives Session and CLIControlRequest<CLIControlPermissionRequest>, returns Behavior)
#### AssistantContentConsumers Interface
The `AssistantContentConsumers` interface handles different types of content within assistant messages:
-`onText`: Handles text content (receives Session and TextAssistantContent)
-`onThinking`: Handles thinking content (receives Session and ThingkingAssistantContent)
-`onToolUse`: Handles tool use content (receives Session and ToolUseAssistantContent)
-`onToolResult`: Handles tool result content (receives Session and ToolResultAssistantContent)
-`onOtherContent`: Handles other content types (receives Session and AssistantContent)
-`onUsage`: Handles usage information (receives Session and AssistantUsage)
-`onPermissionRequest`: Handles permission requests (receives Session and CLIControlPermissionRequest, returns Behavior)
-`onOtherControlRequest`: Handles other control requests (receives Session and ControlRequestPayload, returns ControlResponsePayload)
#### Relationship Between the Interfaces
**Important Note on Event Hierarchy:**
-`SessionEventConsumers` is the **high-level** event processor that handles different message types (system, assistant, user, etc.)
-`AssistantContentConsumers` is the **low-level** content processor that handles different types of content within assistant messages (text, tools, thinking, etc.)
**Processor Relationship:**
-`SessionEventConsumers` → `AssistantContentConsumers` (SessionEventConsumers uses AssistantContentConsumers to process content within assistant messages)
For proper operation, the following timeout relationships should be maintained:
-`onAssistantMessageTimeout` return value should be greater than `onTextTimeout`, `onThinkingTimeout`, `onToolUseTimeout`, `onToolResultTimeout`, and `onOtherContentTimeout` return values
-`onControlRequestTimeout` return value should be greater than `onPermissionRequestTimeout` and `onOtherControlRequestTimeout` return values
### Transport Options
The `TransportOptions` class allows configuration of how the SDK communicates with the Qwen Code CLI:
-`pathToQwenExecutable`: Path to the Qwen Code CLI executable
-`cwd`: Working directory for the CLI process
-`model`: AI model to use for the session
-`permissionMode`: Permission mode that controls tool execution
-`env`: Environment variables to pass to the CLI process
-`maxSessionTurns`: Limits the number of conversation turns in a session
-`coreTools`: List of core tools that should be available to the AI
-`excludeTools`: List of tools to exclude from being available to the AI
-`allowedTools`: List of tools that are pre-approved for use without additional confirmation
-`authType`: Authentication type to use for the session
-`includePartialMessages`: Enables receiving partial messages during streaming responses
-`turnTimeout`: Timeout for a complete turn of conversation
-`messageTimeout`: Timeout for individual messages within a turn
-`resumeSessionId`: ID of a previous session to resume
-`otherOptions`: Additional command-line options to pass to the CLI
### Session Control Features
- **Session creation**: Use `QwenCodeCli.newSession()` to create a new session with custom options
- **Session management**: The `Session` class provides methods to send prompts, handle responses, and manage session state
- **Session cleanup**: Always close sessions using `session.close()` to properly terminate the CLI process
- **Session resumption**: Use `setResumeSessionId()` in `TransportOptions` to resume a previous session
- **Session interruption**: Use `session.interrupt()` to interrupt a currently running prompt
- **Dynamic model switching**: Use `session.setModel()` to change the model during a session
- **Dynamic permission mode switching**: Use `session.setPermissionMode()` to change the permission mode during a session
### Thread Pool Configuration
The SDK uses a thread pool for managing concurrent operations with the following default configuration: