qwen-code ACP Client SDKJava实战指南基于 Agent Client Protocol 构建 AI 智能体客户端【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本文面向希望在 Java 应用中接入 AI 编码智能体的开发者系统讲解 qwen-code 仓库中acp-sdkJava 版 ACP Client SDK的安装引入、核心架构、会话管理、事件处理、权限控制与传输层配置。读完本文你将掌握如何通过几十行 Java 代码启动本地 qwen 智能体进程、创建会话、发送提示词并处理流式回包以及如何扩展文件系统、终端与 MCP 等能力。一、项目概览什么是 ACP Client SDKacp-sdk是 qwen-code 仓库中针对Agent Client ProtocolACP的 Java 客户端 SDK负责让客户端应用与支持 ACP 协议的 AI 智能体如终端里的 qwen CLI进行标准化通信。协议层面它基于 JSON-RPC 2.0 规范通过 JSON schema 统一定义全部消息类型保证了不同客户端与不同 ACP 智能体之间的互操作性。从 client 模块源码结构 看SDK 的核心能力包括会话管理创建new、加载load与关闭会话完整管理对话生命周期文件系统操作文本文件的读写请求ReadTextFileRequest/WriteTextFileRequest终端命令执行创建终端、执行命令、读取输出、等待退出、结束进程等请求工具调用与权限管理处理工具调用更新并对敏感操作进行细粒度授权富内容类型文本、图片、音频、资源、工具调用等多种 Content BlockMCP 集成在会话请求中携带 MCP Server 配置扩展外部工具能力。模块坐标与项目背景可参考 QWEN.md 与 pom.xml。二、环境要求使用该 SDK 前需要准备依赖最低版本说明Java1.8源码编译目标即为 Java 1.8兼容性良好Maven3.6.0用于构建与依赖管理也可使用 Gradle 引入qwen CLI与仓库版本匹配快速开始示例中以子进程方式启动要求本机可执行qwen命令SDK 当前版本为0.0.1-alphaAlpha 阶段Group ID 为com.alibabaArtifact ID 为acp-sdk信息来源于 pom.xml 与 QWEN.md。三、安装与依赖引入3.1 Maven在pom.xml中添加dependency groupIdcom.alibaba/groupId artifactIdacp-sdk/artifactId version0.0.1-alpha/version /dependency3.2 Gradle在build.gradle中添加implementation com.alibaba:acp-sdk:0.0.1-alpha3.3 关键依赖说明SDK 自身的编译期依赖在 pom.xml 中定义包括SLF4J API 2.0.17日志门面业务方可自由绑定日志实现Apache Commons Lang3 3.20.0 与 commons-io 2.21.0参数校验Validate、异常上下文ContextedRuntimeException等工具FastJSON2 2.0.60全部 JSON-RPC 消息的序列化与反序列化JUnit 5 / Logback Classic仅测试作用域用于单元测试与测试日志。构建侧还集成了 checkstylecheckstyle.xml、JaCoCo 覆盖率统计以及面向 Maven Central 的发布插件。四、快速开始创建客户端并建立会话下面的示例直接取自仓库测试用例见 SessionTest.java演示了最简使用链路创建AcpClient→ 发送提示词 → 事件消费 → 关闭客户端。Test public void testSession() throws AgentInitializeException, SessionNewException, IOException { // 创建 ACP 客户端通过进程传输层启动本地 qwen 智能体 AcpClient acpClient new AcpClient( new ProcessTransport(new ProcessTransportOptions().setCommandArgs(new String[] {qwen, --acp, -y}))); try { // 向智能体发送提示词 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 { // 使用完毕务必关闭客户端释放子进程资源 acpClient.close(); } }其中qwen --acp -y表示以子进程方式启动 qwen CLI 并进入 ACP 协议模式--acp为启用 ACP 协议的 CLI 参数-y为自动确认参数具体语义以 qwen CLI 的说明为准。sendPrompt内部会自动完成“新建会话 发送提示词”两个动作在finally中调用close()会关闭传输层并销毁子进程见 AcpClient.close()避免资源泄漏。五、架构与核心组件5.1 四个核心构件按 README 与源码组织SDK 由四个核心构件组成AcpClient客户端主入口类管理到 ACP 智能体的连接。构造时即启动传输层并发起initialize握手负责新建/加载会话、发送提示词、关闭连接Session代表与智能体的一段对话会话封装发送提示词、取消任务以及各类事件/请求的分发处理Transport底层通信抽象承载 JSON-RPC 消息在 stdio 子进程、HTTP 等通道上的收发Protocol Definitions由 schema.json 定义的协议模型生成的 Java 类覆盖所有 ACP 消息类型。5.2 AcpClient 的生命周期与握手AcpClient.java 是整个 SDK 的入口构造流程清晰地体现了 ACP 握手过程调用transport.start()启动传输层对进程传输即拉起子进程构造InitializeRequest并发送等待智能体返回InitializeResponse若初始化响应携带error字段则抛出AgentInitializeException。构造完成后客户端提供三个核心操作newSession()/newSession(NewSessionRequestParams)发送NewSessionRequest依据返回的sessionId创建Session实例失败抛出SessionNewExceptionloadSession(LoadSessionRequestParams)发送LoadSessionRequest恢复既有会话失败抛出SessionLoadExceptionsendPrompt(ListContentBlock, AgentEventConsumer)等价于“新建会话后发送提示词”的组合调用。会话参数如cwd工作目录、mcpServersMCP 服务器列表通过NewSessionRequestParams传递并被透传到后续LoadSessionRequestParams中见 AcpClient.java。5.3 协议结构ACP 协议在 SDK 中被组织为清晰的 JSON-RPC 消息体系见 protocol 包Request / Response 类型客户端与智能体间的请求-响应模型如InitializeRequest、NewSessionRequest、PromptRequest、ReadTextFileRequest等Notification 机制智能体向客户端推送的实时更新如SessionNotification以及客户端发出的CancelNotification错误处理与能力协商JSON-RPCError对象 initialize阶段的能力声明Content Block文本、图片、音频、嵌入资源等多样化的消息内容载体工具调用定义与执行流ToolCallUpdate、ToolCallLocation、ToolCallStatus、ToolKind等模型覆盖工具调用的全生命周期状态。5.4 消息路由与反序列化Session.java 中的toMessage方法展示了 SDK 的消息分派逻辑根据 JSON 中是否包含method、result/error字段分别解析为方法消息MethodMessage、提示词回合结束响应PromptResponse以stopReason为判别标志或普通响应最终统一路由给对应的消费者处理。六、传输层深入ProcessTransport 与超时控制6.1 Transport 接口契约Transport.java 定义了所有传输实现的统一契约isReading()当前是否处于读取状态start()/close()/isAvailable()生命周期管理inputWaitForOneLine(message)发送消息并等待单行响应用于握手类请求inputWaitForMultiLine(message, callback)发送消息并逐行回调处理多行响应用于提示词回合inputNoWaitResponse(message)只发送不等待用于通知类消息。6.2 ProcessTransport 配置项当前仓库内置的传输实现是 ProcessTransport通过ProcessBuilder启动子进程以 stdio 管道承载 JSON-RPC 消息。其配置项集中在 ProcessTransportOptions.java配置项默认值说明commandArgs无必填启动智能体进程的命令行参数如{qwen, --acp, -y}cwd./子进程工作目录turnTimeout30 分钟单个回合一次完整对话轮次的超时messageTimeout180 秒单条消息读取的超时errorHandler打印 error 日志子进程 stderr 输出的消费回调其中turnTimeout作用于inputWaitForOneLine与inputWaitForMultiLine的整轮等待messageTimeout作用于多行迭代中读取单行的时间上限见 ProcessTransport.java。这些超时值定义在 Timeout.javaSDK 预置了 3 秒、60 秒、180 秒、30 分钟四档常量也支持自定义new Timeout(value, timeUnit)。提示ProcessTransport内部会异步读取子进程的 stderr 并通过errorHandler处理同时用AtomicBoolean reading标记读取状态避免并发读写冲突适合作为自定义传输实现如 HTTP Transport的参考范本。七、事件驱动模型AgentEventConsumer 与消费者体系SDK 采用事件消费者模式接收智能体的实时输出。AgentEventConsumer.java 是一个消费者容器可通过链式 setter 挂载五类消费者消费者类型职责典型事件ContentEventConsumer内容与会话状态更新消息块、工具调用、可用命令、当前模式、计划更新FileEventConsumer文件读写请求onReadTextFileRequest、onWriteTextFileRequestTerminalEventConsumer终端操作请求创建/释放终端、读输出、等待退出、结束命令PermissionEventConsumer权限请求处理onRequestPermissionRequestPromptEndEventConsumer提示词回合结束onPromptEnd7.1 会话更新类型ContentEventConsumer可继承 ContentEventSimpleConsumer.java 简化实现需要处理六类会话更新AgentMessageChunkSessionUpdate智能体消息内容块流式更新ToolCallUpdateSessionUpdate/ToolCallSessionUpdate工具调用的进行中/最终状态AvailableCommandsUpdateSessionUpdate可用命令列表变更CurrentModeUpdateSessionUpdate当前会话模式变更PlanSessionUpdate计划条目更新对应Plan/PlanEntry/PlanEntryStatus/PlanEntryPriority模型。7.2 事件分发的超时与异常语义在 Session.java 中事件处理分为两类通知类NoWait调用消费回调并在超时内完成超时默认 60 秒defaultEventConsumeTimeout请求类Request如权限请求、文件读写、终端操作处理器返回结果后由 SDK 自动构造Response回传给智能体若消费过程抛出EventConsumeException或超时则回传 JSON-RPCINTERNAL_ERROR。这一机制让业务方可以同步决策比如“是否允许写文件”而无需关心底层请求-响应编解码。八、能力协商与权限控制8.1 初始化阶段声明客户端能力InitializeRequestParams见 InitializeRequest.java携带协议版本、clientCapabilities与clientInfo。其中ClientCapabilities用于声明客户端支持的能力例如在 SessionTest.java 中AcpClient acpClient new AcpClient(transport, new InitializeRequestParams().setClientCapabilities( new ClientCapabilities() .setTerminal(true) .setFs(new FileSystemCapability().setReadTextFile(true).setWriteTextFile(true))));上述代码声明客户端支持终端能力、可读写文本文件从而让智能体在会话中放心发起相应的请求。8.2 权限请求处理示例当智能体需要执行敏感操作如创建文件时会向客户端发送RequestPermissionRequest由PermissionEventConsumer决定放行方式。仓库测试给出了一个“自动选择 ALLOW_ALWAYS”的完整实现session.sendPrompt(Collections.singletonList(new TextContent(创建一个test.touch文件)), new AgentEventConsumer() .setFileEventConsumer(new FileEventSimpleConsumer()) .setPermissionEventConsumer(new PermissionEventConsumer() { Override public RequestPermissionResponseResult onRequestPermissionRequest(RequestPermissionRequest request) throws EventConsumeException { return new RequestPermissionResponseResult(new RequestPermissionOutcome() .setOptionId(Optional.of(request) .map(MethodMessage::getParams) .map(RequestPermissionRequestParams::getOptions) .flatMap(options - options.stream() .filter(option - ALLOW_ALWAYS.equals(option.getKind())) .findFirst()) .map(PermissionOption::getOptionId).orElse(null)) .setOutcome(PermissionOutcomeKind.SELECTED)); } Override public Timeout onRequestPermissionRequestTimeout(RequestPermissionRequest request) { return Timeout.TIMEOUT_60_SECONDS; } }));这里 SDK 在智能体给出的多个权限选项中PermissionOption种类见PermissionOptionKind自动挑选ALLOW_ALWAYS并通过PermissionOutcomeKind.SELECTED回传选择结果。企业应用可在此处接入自己的审批系统如工单、人工审核实现对敏感操作的可控授权。九、典型使用场景结合 SDK 能力与仓库定位acp-sdk适用的场景包括企业应用内的 AI 智能体集成在业务系统中嵌入本地编码智能体通过统一协议交互自动化脚本与任务执行程序化向智能体下发任务并处理结果文件系统操作自动化借助文件事件消费者实现文本文件的受控读写终端命令执行与结果处理通过终端事件消费者驱动命令行任务外部服务与工具集成通过NewSessionRequestParams携带 MCP Server 配置扩展智能体工具集。十、构建与测试10.1 构建命令在packages/sdk-java/client目录下执行# 编译项目 mvn compile # 运行测试 mvn test # 打包 JAR mvn package # 安装到本地仓库 mvn install构建配置的细节值得注意Maven Surefire 配置了failIfNoTeststrue且排除了integration测试组见 pom.xml这意味着依赖真实 qwen 子进程的集成测试如SessionTest的Tag(integration)在默认mvn test下不会执行保证单元测试可在无智能体环境运行Checkstyle 在构建期强制执行代码规范JaCoCo 在测试阶段生成覆盖率报告。10.2 测试覆盖仓库测试覆盖了协议枚举PermissionOptionKindTest、PlanEntryStatusTest、StopReasonTest、ToolCallStatusTest、ToolKindTest、PlanEntryPriorityTest、会话管理SessionTest、线程池配置ThreadPoolConfigTest等对应路径见 client 测试目录。测试重点验证协议消息生成、会话管理功能、权限处理工作流、内容类型处理。十一、开发约定与许可SDK 遵循标准 Java 编码规范使用 SLF4J 日志门面基于 JSON-RPC 2.0 规范通信采用 FastJSON2 完成序列化详见 QWEN.md项目采用 Apache 2.0 许可参见仓库根目录 LICENSE欢迎通过 Issues 与 Pull Requests 参与贡献遇到问题可通过 GitHub Issues 反馈。十二、延伸阅读SDK 上下文总览QWEN.md构建与发布配置pom.xml客户端入口与握手逻辑AcpClient.java会话事件分发与请求处理Session.java传输层接口与进程实现Transport.java、ProcessTransport.java传输配置项与超时定义ProcessTransportOptions.java、Timeout.java集成测试示例SessionTest.java【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考