qwen-code/packages/sdk-java/client/README.md

ACP Client SDK (Agent Client Protocol Java SDK For Client)

The ACP Client SDK is a Java Software Development Kit for communicating with AI agents that support the Agent Client Protocol (ACP). It provides a standardized way to interact with AI agents that support the Agent Client Protocol, enabling features like session management, file system operations, terminal commands, and tool calls.

Project Overview

The ACP SDK implements the Agent Client Protocol, allowing client applications to communicate with AI agents. The SDK provides the following core features:

• Session management (create, load, manage conversations)
• File system operations (read/write text files)
• Terminal command execution
• Tool call handling and permission management
• Support for rich content types (text, images, audio, resources)
• Integration with Model Context Protocol (MCP) servers

Requirements

• Java 8 or higher
• Maven 3.6.0 or higher

Features

• Standardized Protocol: Implements ACP protocol to ensure interoperability with various ACP-compatible agents
• Flexible Transport Layer: Supports multiple transport mechanisms (stdio, HTTP, etc.)
• Session Management: Complete session lifecycle management
• Permission Control: Fine-grained permission management to protect sensitive operations
• Content Block Handling: Support for multiple data types in content blocks
• MCP Integration: Integration with external MCP servers for extended tooling capabilities

Installation

Maven

Add the following dependency to your pom.xml file:

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>acp-sdk</artifactId>
    <version>0.0.1-alpha</version>
</dependency>

Gradle

Add the following to your build.gradle file:

implementation 'com.alibaba:acp-sdk:0.0.1-alpha'

Quick Start

The following is a simple example showing how to use the ACP SDK to create a client and establish a session:

@Test
public void testSession() throws AgentInitializeException, SessionNewException, IOException {
    // Create an ACP client with a process transport
    AcpClient acpClient = new AcpClient(
            new ProcessTransport(new ProcessTransportOptions().setCommandArgs(new String[] {"qwen", "--acp", "-y"})));

    try {
        // Send a prompt to the agent
        acpClient.sendPrompt(Collections.singletonList(new TextContent("你是谁")),
                new AgentEventConsumer().setContentEventConsumer(new ContentEventSimpleConsumer() {
                    @Override
                    public void onAgentMessageChunkSessionUpdate(AgentMessageChunkSessionUpdate sessionUpdate) {
                        logger.info(sessionUpdate.toString());
                    }

                    @Override
                    public void onAvailableCommandsUpdateSessionUpdate(AvailableCommandsUpdateSessionUpdate sessionUpdate) {
                        logger.info(sessionUpdate.toString());
                    }

                    @Override
                    public void onCurrentModeUpdateSessionUpdate(CurrentModeUpdateSessionUpdate sessionUpdate) {
                        logger.info(sessionUpdate.toString());
                    }

                    @Override
                    public void onPlanSessionUpdate(PlanSessionUpdate sessionUpdate) {
                        logger.info(sessionUpdate.toString());
                    }

                    @Override
                    public void onToolCallUpdateSessionUpdate(ToolCallUpdateSessionUpdate sessionUpdate) {
                        logger.info(sessionUpdate.toString());
                    }

                    @Override
                    public void onToolCallSessionUpdate(ToolCallSessionUpdate sessionUpdate) {
                        logger.info(sessionUpdate.toString());
                    }
                }));
    } finally {
        // Close the client when done
        acpClient.close();
    }
}

Architecture Components

Core Components

1. AcpClient: Main client class that manages connections to ACP-compatible agents
2. Session: Represents a conversation session with an agent
3. Transport: Handles the underlying communication protocol (JSON-RPC over stdio, HTTP, etc.)
4. Protocol Definitions: Generated from JSON schema, defining all ACP message types

Protocol Structure

The SDK implements the Agent Client Protocol based on a comprehensive JSON schema that defines:

• Request/Response types for agent-client communication
• Notification mechanisms for real-time updates
• Error handling and capability negotiation
• Content blocks for various data types
• Tool call definitions and execution flows

Use Cases

• AI agent integration in enterprise applications
• Automated scripting and task execution
• File system operation automation
• Terminal command execution and result processing
• Integration with external services and tools

Development

Build

# Compile the project
mvn compile

# Run tests
mvn test

# Package the JAR
mvn package

# Install to local repository
mvn install

Testing

The project includes comprehensive unit tests covering:

• Protocol message generation from JSON schema
• Session management functionality
• Permission handling workflows
• Content type processing

Dependencies

Key dependencies include:

• SLF4J API for logging
• Apache Commons Lang3 and IO for utility functions
• FastJSON2 for JSON serialization/deserialization
• JUnit 5 for testing
• Logback Classic for testing logging

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please submit issues and pull requests.

Support

If you encounter any problems, please submit an issue report through GitHub Issues.