ACP 集成

Table of contents

通过代理客户端协议（Agent Client Protocol，ACP）在你的编辑器中直接运行 cagent 代理。你的代理将获得编辑器文件系统上下文的访问权限，并能在你工作时读取和修改文件。编辑器负责文件操作，而 cagent 提供 AI 能力。

本指南展示了如何配置 Neovim 或 Zed 来运行 cagent 代理。如果你希望将 cagent 代理作为工具暴露给 Claude Desktop 或 Claude Code 等 MCP 客户端，请参阅 MCP 集成。

工作原理

当你使用 ACP 运行 cagent 时，它会成为你编辑器环境的一部分。你可以选择代码、高亮函数或引用文件——代理能看到你所看到的内容。无需复制文件路径或切换到终端。

询问“解释这个函数”，代理会读取你正在查看的文件。要求它“添加错误处理”，它会在你的编辑器中直接编辑代码。代理基于编辑器对项目的视图工作，而不是通过外部文件系统进行导航。

与在终端中运行 cagent 的区别：文件操作通过编辑器进行，而不是代理直接访问你的文件系统。当代理需要读取或写入文件时，它会向你的编辑器请求。这确保了代理对代码的视图与你的视图保持同步——相同的当前工作目录、相同的文件、相同的状态。

前置条件

在配置编辑器之前，你需要：

  • 已安装 cagent - 参阅 安装指南
  • 代理配置 - 定义代理的 YAML 文件。参阅 教程 或 示例配置
  • 支持 ACP 的编辑器 - Neovim、Intellij、Zed 等

你的代理将使用 shell 环境中的模型提供商 API 密钥（ANTHROPIC_API_KEY、OPENAI_API_KEY 等）。在启动编辑器之前，请确保这些密钥已设置。

编辑器配置

Zed

Zed 内置了 ACP 支持。

  1. 在 settings.json 中将 cagent 添加到你的代理服务器：

    {
  "agent_servers": {
    "my-cagent-team": {
      "command": "cagent",
      "args": ["acp", "agent.yml"]
    }
  }
}

    替换：

    • my-cagent-team 为你想为代理使用的名称
    • agent.yml 为你的代理配置文件路径

    如果你有多个需要分别运行的代理文件，可以在 agent_servers 下为每个代理创建多个条目。

  2. 启动一个新的外部代理线程。在下拉列表中选择你的代理。

    Zed 中使用 cagent 的新外部线程

Neovim

使用 CodeCompanion 插件，它通过内置适配器原生支持 cagent：

  1. 通过你的插件管理器 安装 CodeCompanion。

  2. 在你的 CodeCompanion 配置中扩展 cagent 适配器：

    require("codecompanion").setup({
  adapters = {
    acp = {
      cagent = function()
        return require("codecompanion.adapters").extend("cagent", {
          commands = {
            default = {
              "cagent",
              "acp",
              "agent.yml",
            },
          },
        })
      end,
    },
  },
})

    将 agent.yml 替换为你的代理配置文件路径。如果你有多个需要分别运行的代理文件，可以为每个代理创建多个命令。

  3. 重启 Neovim 并启动 CodeCompanion：

    :CodeCompanion

  4. 切换到 cagent 适配器（默认在 CodeCompanion 缓冲区中使用键位 ga）。

参阅 CodeCompanion ACP 文档 了解 CodeCompanion 中 ACP 支持的更多信息。注意终端操作不受支持，因此通过 CodeCompanion 无法使用 shell 或 script_shell 等 工具集。

代理引用

你可以将代理配置指定为本地文件路径或 OCI 注册表引用：

# 本地文件路径
$ cagent acp ./agent.yml

# OCI 注册表引用
$ cagent acp agentcatalog/pirate
$ cagent acp dockereng/myagent:v1.0.0

在你的编辑器配置中使用相同的语法：

{
  "agent_servers": {
    "myagent": {
      "command": "cagent",
      "args": ["acp", "agentcatalog/pirate"]
    }
  }
}

注册表引用支持团队共享、版本管理和不依赖本地文件路径的简洁配置。详情参阅 共享代理 了解使用 OCI 注册表的信息。

测试你的设置

验证你的配置是否正常工作：

  1. 使用编辑器配置的方法启动 cagent ACP 服务器
  2. 通过编辑器界面发送测试提示
  3. 检查代理是否响应
  4. 要求代理读取文件，验证文件操作是否正常工作

如果代理启动但无法访问文件或执行其他操作，请检查：

  • 编辑器中的工作目录是否正确设置为项目根目录
  • 代理配置文件路径是绝对路径或相对于工作目录的相对路径
  • 你的编辑器或插件是否正确实现了 ACP 协议功能

后续步骤