AgentConnect
连接与自动化

VS Code

在 VS Code 里和 Agent 对话,查看它工作区里的文件,并以整文件 diff 的方式审阅它的修改。

Agent 是一个 Agent Host Protocol(AHP)主机,所以 VS Code 可以把它作为远程 agent host 打开。你在 VS Code 的聊天里和 Agent 对话,以 diff 审阅每一处修改,并读取它工作区里的文件。Agent 仍然运行在原来的地方,VS Code 只是多了一个看它的窗口。如果是要把 Agent 接到你自己的聊天界面上,见选择协议。

在 VS Code 里和 Agent 对话,旁边打开着它工作区里的一个文件

这是预览功能。VS Code 自身没有 AgentConnect 的登录方式,所以需要手动安装 AgentConnect 扩展:它用到的一个 VS Code API 还处于提案阶段,因此没有上架 Marketplace。

一共四步:

  1. 给 Agent 添加 AHP API。
  2. 安装 AgentConnect 扩展。
  3. 把 Agent 的接口加到 VS Code。
  4. 登录。

给 Agent 添加 API

Agent 的所有者给它添加 API 之后,Agent 才接受 AHP 客户端。开始之前,先确认 Agent 所在的 Daemon 是 v2.14.0 或更新的版本;不是的话先升级。

  1. 在控制台打开 Agent,进入它的 集成 页。
  2. 点 添加集成,在 工作流 下选 API。
  3. 在 协议 下选 AHP v1。
  4. 点 添加 API。

添加集成对话框,已选中 AHP v1 协议

协议上可能带有一个标记:

标记含义
无能看到这个 Agent 的成员都可以连接。
试点可以添加 API,但只有获批参加试点的成员可以连接。
未启用当前部署没有开启 AHP,协议无法选择。在 AgentConnect OSS 上,先开启它。

之后集成页会出现一张 API 卡片。打开它的 快速开始,复制其中的 WebSocket 地址,这就是在 VS Code 里用的 Agent 地址:

集成页上的 API 卡片和它的快速开始按钮

wss://<relay-url>/ahp/agents/<agent-id>

每个 Agent 有自己的接口,所以要在 VS Code 里打开的每个 Agent 都要添加 API。

安装扩展

从 v2.15.0 起,每个 AgentConnect 正式发布版都附带这个扩展的 VSIX 文件。

  1. 下载 agentconnect-vscode.vsix。这个链接始终指向最新发布版的文件。

  2. 安装。在 VS Code 的命令面板运行 Extensions: Install from VSIX... 并选择这个文件,或者在终端里运行:

    code --install-extension agentconnect-vscode.vsix
  3. 允许扩展使用提案 API。在命令面板运行 Preferences: Configure Runtime Arguments,在打开的 argv.json 里加入这一行:

    { "enable-proposed-api": ["agentconnect.agentconnect-vscode"] }
  4. 重启 VS Code。

如果只想试用而不改 argv.json,可以带上这个参数启动一次 VS Code:

code --enable-proposed-api=agentconnect.agentconnect-vscode

扩展不会自动更新。要更新时,重新下载文件并覆盖安装。

把 Agent 加到 VS Code

在一个你信任的文件夹里,把接口写进 .vscode/settings.json:

{
  "chat.workspaceRemoteAgentHosts": [
    { "name": "AgentConnect", "address": "wss://<relay-url>/ahp/agents/<agent-id>" }
  ]
}

新建一个聊天,在会话类型里选这个 Agent。它以自己的名字列出,后面跟着你给这一项起的名字。

如果用的是 VS Code 的 Agents 窗口,改为在命令面板运行 Add Remote Agent Host...,或者在用户设置里配置 chat.remoteAgentHosts。编辑器窗口只读取工作区设置。

地址不接受查询字符串,所以密钥或令牌不能放在地址里。

登录

在命令面板运行 AgentConnect: Sign In to an Agent。浏览器会打开 AgentConnect 控制台:按提示登录,并批准 VS Code 访问这个 Agent。之后 VS Code 完成连接,聊天的会话类型里占位名会换成 Agent 的名字。

  • 登录状态会一直保持,直到你运行 AgentConnect: Sign Out,或者在控制台的 个人资料 里断开 VS Code。
  • 每个 Agent 是一个独立的接口,需要单独批准。
  • 同一个组织一次只登录一个 Agent。同时登录两个时,VS Code 会把较新的登录发给两者,先登录的那个 Agent 会拒绝它。

你会看到什么

对话

每个聊天是这个 Agent 的一个会话,会实时显示 Agent 的回复、工具调用和修改。

  • Agent 使用它自己配置的模型。VS Code 的模型选择器只有一项,选择不起作用。
  • 每条消息只有一张图片会送到 Agent,其他附件会被丢弃。

以整文件 diff 查看修改

每处修改会在聊天里显示增删行数。点击文件可以打开整个文件的 diff,而不只是改动的那几行。

Agent 一处修改的 diff,显示整个文件

Agent 的文件

VS Code 以只读方式读取 Agent 工作区里的文件。你打开着的文件会在 Agent 修改它之后自动刷新。

要浏览工作区,先打开和 Agent 的聊天,再运行 AgentConnect: Add an Agent's Workspace to the Explorer。它会把该会话的工作目录作为一个文件夹加到资源管理器。

聊天旁边打开着 Agent 工作区里的一个文件

限制

  • 文件只读,大于约 44 KiB 的文件打不开。
  • 只要被修改的那几行还保持 Agent 改完时的样子,diff 就显示整个文件。同样的行被再次修改之后,diff 只显示改动的行。
  • 打开的文件会在 Agent 自己修改之后刷新。Agent 运行的命令造成的改动不会通知 VS Code。
  • 符号链接不会列出,也打不开。
  • 文件内容里 Agent 的密钥值会被掩码,和工具输出一样。

从脚本访问

API 卡片的 快速开始 里有一个基于微软 @microsoft/agent-host-protocol 客户端的 Node 示例。它用一个能看到该 Agent 的成员的 完全访问 API 密钥登录;Agent 对话 密钥会被拒绝。把密钥放在你信任的服务器上,不要放进 URL 或命令行参数。

在 AgentConnect OSS 上

AHP 默认关闭。设置以下各项并重启服务:

服务设置值
控制平面和每个 relayAHP_MODEon
控制平面PUBLIC_RELAY_URLrelay 的公开 URL。
每个 relayAHP_AUTHORIZATION_SERVER控制平面的 OAuth issuer,VS Code 向它登录。
控制平面AHP_PUBLIC_ACCESStrue 表示放行所有成员。试点阶段保持 false,并在 AHP_TEST_USER_IDS 里列出成员。

守护进程从 v2.14.0 起无需设置即提供 AHP。

故障排查

  • 连上了,但没有任何反应,消息发不出去:VS Code 没有登录。确认扩展已安装并列在 enable-proposed-api 里,然后登录。
  • Agents 窗口里出现 “The terminal process failed to launch: Unknown method”:Agents 窗口会向 Agent 请求终端,这个功能不可用。聊天不受影响。
  • 聊天里出现 “Unknown method”:Agent 的守护进程早于 v2.14.0。升级它。
  • 连接被拒绝:组织没有开启 AHP,或者 Agent 没有添加 AHP API。按上面的步骤给 Agent 添加 API。
  • 文件打不开:它大于约 44 KiB,或者是符号链接。

How is this guide?

本页目录

How is this guide?