Agent Client Protocol（ACP）

AI Assistant 支持 Agent Client Protocol (ACP) ，允许您连接外部 AI 代理并在 AI 聊天中使用。 ACP 定义了标准通信接口，因此任何实现该协议的代理都可以添加，无需自定义集成。

ACP 兼容的代理可以通过精选的注册表安装，也可以手动设置。注册表中的代理无需额外设置，自定义代理则需要进行配置。

在哪里获取代理

作为起点，您可以浏览 ACP 兼容代理的注册表。其中列出了一组无需手动设置即可使用的精选代理。

或者，访问官方 ACP 网站以查看兼容代理列表。链接的代理页面提供下载说明及所需的配置信息。

限制

目前，ACP 兼容代理不支持在 Windows Subsystem for Linux（WSL ）中使用。

从注册表安装代理程序。

您可以从注册表中选择并安装代理，注册表中包含可直接在 IDE 中访问的精选 ACP 兼容代理列表。

打开 AI 聊天工具窗口。
点击打开聊天模式选择器，并选择从 ACP 注册表安装选项。
或者，转到设置 | 工具 | AI Assistant | 代理。
在代理页面，安装您要使用的代理程序。此外，根据需要配置 MCP 设置。
- 传递自定义 MCP 服务器 – 启用此设置可将已配置的 MCP 服务器暴露给已安装的代理程序。
- 传递 IntelliJ MCP 服务器 – 启用此设置可将集成的 IntelliJ MCP 服务器暴露给已安装的代理程序。
点击确定以应用更改。

安装过程中，IDE 会自动：

下载所需的代理文件。
根据需要下载并管理 Node.js 或 Python 运行环境。若已存在兼容的运行环境，IDE 将自动复用。
为代理做好使用准备。

安装完成后，所选代理即可在 AI 聊天中使用。

更新代理程序

如果有新版代理可用，其旁边会出现一个蓝点。

您可以按以下方式从注册表更新代理程序：

请导航至设置 | 工具 | AI Assistant | 代理。
找到有新版可用的代理程序。
点击更新。
点击确定以应用更改。

卸载代理程序

要卸载代理程序：

请导航至设置 | 工具 | AI Assistant | 代理。
找到要卸载的代理程序。
点击卸载。
点击确定以应用更改。

添加自定义代理

如果您要添加未在注册表中列出的自定义代理，需要在 acp.json 文件中提供其配置信息：

打开 AI 聊天工具窗口。
在 AI 聊天工具窗口右上角点击按钮，选择添加自定义代理人或代理程序 (Agent)。
选择该选项将在 acp.json 中创建位于 ~/.jetbrains/acp.json 的文件，并打开用于编辑，您需要在其中提供配置详情。
在配置文件中填写您的代理信息。如有需要，您可以添加多个代理。配置必须遵循以下格式：如有需要，您可以添加多个代理。配置必须符合以下格式：
{ "default_mcp_settings": {}, "agent_servers": { "Example Agent": { "command": "/path/to/agent", "args": [ "acp" ], "env": { "API_KEY": "your-api-key-here" } } } }
- default_mcp_settings – 定义应用于所有本地代理的默认 MCP 配置，除非被代理专用 MCP 设置覆盖。有两个选项：
  - use_custom_mcp – 控制用户配置的 MCP 服务器是否对代理 Exposed。默认设置为 true。
  - use_idea_mcp – 控制集成 IntelliJ MCP 服务器是否暴露给代理程序。默认设置为 false。当此选项设置为 true 时，您可以通过指定 idea_mcp_allowed_tools 键，选择性地限制集成 MCP 服务器可用的工具。如未指定，将把集成 MCP 服务器中所有可用的工具暴露给代理程序。
- agent_servers – 顶层对象，包含所有已配置代理程序。此对象中的每个键都是代理程序在 AI 聊天中显示的名称。
- Example Agent – 用作标识代理程序的显示名称。
- command – 代理程序可执行文件的路径。 AI Assistant 会作为子进程启动该文件。
- args – 启动代理程序时传递给它的命令行参数数组。
- env – 为代理进程设置的环境变量集合。
  虽然示例中包含了 API_KEY ，但大多数代理并不需要。通常需要在终端中手动运行代理，并根据提供的说明进行身份验证。您输入的凭据会保存在您的用户配置中，因此代理在下次启动时将不再要求您再次输入这些凭据。
请参考您的代理文档，了解代理特定的配置细节，如支持的实参或所需的环境变量。
IDE 可以检测到已安装在您电脑上的 ACP 兼容代理，并提供将其添加到配置中的选项。要执行此操作，请点击添加到配置。

完成配置后，代理程序即可在 AI 聊天中选择使用。已添加的代理通过图标表示。

要使用已配置的代理程序，请在列表中选择，输入提示词后发送。

收集 ACP 日志

要收集已配置代理的日志，请点击按钮，该按钮位于 AI 聊天工具窗口的右上角，然后选择获取 ACP 日志。这将下载包含代理日志的归档文件。

要收集更详细的日志，包括所有发给代理的请求和回复，请在 Registry 中启用 llm.agent.extended.logging 键：

在主菜单中，转到导航 | 全局搜索或按两次 Shift 以打开搜索窗口。
输入 Registry 并按 Enter。
在打开的对话框中，使用 Ctrl+F 查找 llm.agent.extended.logging 键，并启用它。
点击关闭并重启 IDE 以应用更改。

重启 IDE 后，您可以照常通过获取 ACP 日志收集日志。

配置示例

本节展示 ACP 配置文件可能的示例：

                    {
                        "default_mcp_settings": {
                            "use_idea_mcp": true,
                            "use_custom_mcp": true
                        },
                        "agent_servers": {
                            "openode": {
                                "command": "/Users/<username>/.opencode/bin/opencode",
                                "args": [
                                    "acp"
                                ]
                            },
                            "goose": {
                                "command": "/Users/<username>/.local/bin/goose",
                                "args": [
                                    "acp"
                                ]
                            },
                            "auggie": {
                                "command": "/Users/<username>/.nvm/versions/node/v20.5.0/bin/auggie",
                                "args": [
                                    "--acp"
                                ]
                            }
                        }
                    }
        
  

故障排查

本节包含兼容 ACP 的代理的故障排除提示。

添加的代理未显示在列表中

添加到 acp.json 文件中的代理应立即在 AI 聊天中显示。如果代理未出现在列表中：

请检查 acp.json 文件的格式是否正确。
重启 IDE。

代理启动失败

如果自定义代理启动失败，请尝试以下方法：

确保提供的所有参数具有正确的值，因为不同的代理可能需要不同的密钥或实参。
在 command 参数中使用代理可执行文件的完整路径。
如果代理支持控制台模式，请尝试在终端中手动运行以验证其是否正常工作。

如果问题仍然存在，请执行以下操作：

收集日志。
复制您的 acp.json 配置（复制前请移除任何敏感信息）。
截图或录制简短视频以说明问题。
在 YouTrack 中创建问题。
将截图、日志和配置文件附加到问题中。

2026年 3月 16日