如何在 IntelliJ IDEA 中通过 ACP 使用 AI 智能体

Sue

Read this post in other languages:

• English

Agent Client Protocol (ACP) 定义了客户端（如 IntelliJ IDEA）与智能体之间的通用契约。IntelliJ IDEA 已包含多种兼容 ACP 的智能体，包括 Codex、Claude Agent 和 Junie。除了这些绑定的选项之外，ACP Registry 还提供了更多选择，团队可以通过 acp.json 注册内部或不公开列出的智能体。

核心理念是边界。IntelliJ IDEA 仍然是您浏览项目、检查代码和审查更改的环境。通过 ACP 连接，每个智能体都维护自己的模型、行为、身份验证和智能体端工具。

这样一来，可替换单元的规模便会大于 LLM。兼容 ACP 的智能体包含围绕模型搭建的完整框架：规划逻辑、工具、模型路由行为以及可观测性。由于 ACP 将 IDE 与智能体之间的边界标准化，您可以顺畅地从一个智能体切换为另一个智能体，而无需更改 IntelliJ IDEA 与其集成的方式。 

ACP 简介

我们通常将 ACP 称为面向编码智能体的 LSP (Language Server Protocol)。这个类比十分贴切，因为二者面临的集成问题相似。

在 LSP 出现之前，支持每种语言意味着编写单独的编辑器集成。LSP 用单一契约取代了矩阵式集成方式。

ACP 将同一思路应用到编辑器或 IDE 与编码智能体之间的连接上。任何兼容 ACP 的智能体均可连接，不需要为每个配对开发定制插件或调用私有 API。

ACP 源自于 JetBrains 与 Zed 的合作，在项目之初，双方就将 JetBrains IDE 和 Zed 设定为客户端。

对于本地智能体，IntelliJ IDEA 会启动一个子进程，并通过标准输入输出基于 JSON-RPC 与之进行通信。在初始化期间，IDE 和智能体会协商协议版本和相应的功能。连接建立后，提示会发送到智能体，而进度更新、文件操作和权限请求则返回给 IDE。

在这套共享契约之下，智能体依然可以有不同的行为表现。在初始化期间，每个智能体都会声明其支持的可选功能。计划、模式、斜杠命令、会话加载、终端操作和其他功能在不同智能体间可能有所不同。

ACP 负责 IntelliJ IDEA 与智能体之间的交互。额外的工具和上下文可以通过 MCP (Model Context Protocol) 传递给智能体，包括用户配置的服务器和集成的 IntelliJ MCP 服务器。

从可用智能体开始

IntelliJ IDEA 预装了多款智能体（包括 Codex、Claude Agent 和 Junie），无需手动配置 ACP 即可使用。选择一个智能体，并描述您想要它处理的任务。

每个智能体都有自己的工作流风格，可能包括规划模式、斜杠命令或特定的身份验证流程。借助 ACP，IntelliJ IDEA 可以通过共享契约承载这种交互，同时保留不同智能体的差异。

让智能体完成一个小改动。在智能体完成文件编辑后，AI 聊天会在对话中显示已更改的文件。点击该文件即可在聊天旁的编辑器中打开差异对比，并查看具体的变更内容。

这种“编辑并审查”的循环是值得保留的部分。如果您稍后切换智能体，在 IDE 内保留此循环后，您便无需迁移项目，也无需在单独的工具中审查更改。

通过 ACP Registry 安装智能体

ACP Registry 包含其他兼容 ACP 的智能体，以及 IntelliJ IDEA 安装这些智能体所需的元数据。

在 IntelliJ IDEA 中，打开 Settings | Tools | AI Assistant | Agents（设置 | 工具 | AI Assistant | 智能体），然后从注册表中选择一个智能体。最新的 ACP 文档描述了完整的安装流程。

利用智能体的配置视图，您还可以公开在 AI Assistant 中配置的 MCP 服务器、集成的 IntelliJ MCP 服务器，或者同时公开两者。

当您应用设置时，IntelliJ IDEA 会下载智能体文件。首次启动会话时，系统可能会要求您使用该智能体支持的方式完成身份认证。

注册表还提供了用于更新和卸载的元数据。这些操作都在 Agents（智能体）设置中完成，因此添加智能体无需维护另一个 IDE 插件。

每个注册表中的智能体都有其自己的许可证、服务、凭据和隐私条款。在授予仓库访问权限之前，请先查看这些详细信息。

使用 acp.json 连接自定义智能体

注册表中的智能体用于广泛分发。而内部智能体的作用范围通常较小，应保留在公司内部。

如果内部智能体实现 ACP，请在 ~/.jetbrains/acp.json 中注册该智能体。IntelliJ IDEA 提供的 Add Custom Agent（添加自定义智能体）操作会创建并打开此文件，但您也可以直接编辑此文件。

以下配置注册了一个假设的公司迁移智能体：

{
  "agent_servers": {
    "Company Migration Agent": {
      "command": "/opt/company/bin/migration-agent",
      "args": ["acp"]
    }
  }
}

agent_servers 下的每个键都会成为该智能体的显示名称。command 值必须包含 IntelliJ IDEA 将要启动的可执行文件的完整路径。将激活该智能体的 ACP 模式所需的实参放在 args 中；确切值来自智能体文档。

当进程需要环境变量时，使用 env。很多智能体期望您先通过其 CLI 进行身份验证，然后重用存储在智能体用户配置中的凭据。如果智能体通过 env 接受 API 密钥，请按照其文档进行操作，并避免将该文件或其密钥提交到仓库。

保存 acp.json，然后在 IntelliJ IDEA 中选择已配置的智能体。

如果机器上已安装任何兼容 ACP 的智能体，IDE 将检测到这些智能体，并提供将其添加到配置的选项。

为什么要使用多个智能体？

团队可能需要使用不同的智能体来处理不同类型的工作。ACP 为这些智能体提供了连接到 IntelliJ IDEA 的通用方式：

• 通过 `acp.json` 连接兼容 ACP 的智能体可以避免开发和维护单独的 IntelliJ IDEA 插件。
• 导航、编辑和差异审查仍保留在 IntelliJ IDEA 中，而开发者可以选择工作所需的智能体。
• 如果某个智能体的服务或模型提供商不可用，开发者可以切换到另一个已配置的智能体，并在同一个 IntelliJ IDEA 项目中继续工作。

保留 IDE，选择智能体

使用 IntelliJ IDEA 中已有的智能体，通过 ACP Registry 安装一个智能体，或在 acp.json 中注册一个内部智能体。

ACP 将编码智能体从 IDE 的绑定组件转变为一种可以随时重新调整的可替换选择。

本博文英文原作者：

Anton Arhipov