利用 ACP 协议构建 AI 编程代理集成

在实际的 AI 编程场景中，很多开发者会走进一个误区：以为让代理干活，就是向它丢去一句命令行。但如果你需要让 Codex 去检查一台远程虚拟机里的仓库，它必须读取代码副本、在那边执行命令、向你申请权限，再把更新结果回传给你的应用。这其实是一次完整的会话，而不是一条单薄的 shell 指令。而 Agent Client Protocol（简称 ACP）正是为了统一这种会话而生。

ACP 究竟解决了什么问题？

ACP 为客户端和编程代理定义了一份共享的会话契约。简单来说，客户端启动一个支持 ACP 的代理进程，初始化连接、创建会话、发送提示词、接收更新、处理代理发来的请求，最后优雅地关闭会话。整个过程通过 stdin 和 stdout 交换消息，这种机制非常适合跑在远程环境里的代理——你不必关心代理具体部署在哪台机器，只要协议连通，消息就能正常流动。

这个协议原本是为本地应用设计的，比如一个代码编辑器，在同一个机器上启动编程代理，通过标准输入输出沟通。但我们完全可以把相同的机制搬到远程：你的应用留在本地，编程代理则运行在一个隔离的 Remote Sandbox 里。协议负责把两者连接起来，它不负责创建沙盒，也不负责安装代理，但一旦 Codex、OpenCode 或 Pi 都跑起来，它们就能共用同一套连接方式。

在实现层面，共用客户端直接使用 ACP 官方的 TypeScript SDK，通过类型安全的方式快速搭建起连接逻辑。

以 AML 为例：代理会话与执行环境解耦

为了具体说明，我们以 Agent Markup Language（简称 AML）为例。这是一个基于 MIT 许可的 TypeScript 和 JSX 运行时，用于编排代理工作流、工具、沙盒以及持久化工作空间。我们最近把 AML 内置的编程代理全部迁移到了 ACP 上，让代理的会话生命周期不再随着所选执行环境的不同而改变。

在 AML 中，Sandbox 和 Workspace 是两类被命名的运行时资源，不是泛指的概念。Sandbox 提供执行环境并挂载工作文件，Workspace 则负责持有这些文件以及它们的持久化。一个 AML 的 Agent provider 是对编程代理的统一接口，codexAgent()、opencodeAgent()、piAgent() 各自返回一个 provider。每个 provider 只负责映射对应代理自身的配置和能力，而共享运行时负责统一处理会话、消息、stdin/stdout、MCP 服务器、取消操作和资源清理。

这样的设计让 Coding Automation 变得真正可复用：你在本地开发的编排逻辑，可以无缝切换到不同代理上，而无需重写会话管理代码。

远程运行代理的两个基本前提

要将一个 AI 代理跑在远程环境中，你需要满足两个条件。第一，远程机器上已经安装了对应的代理程序；第二，你的应用能够向它发送提示，持续接收更新，并在工作结束时把它停下来。ACP 所做的，就是把你应用和代理之间的交互协议标准化，它不会替你安装任何东西。

假如你的远程容器或云主机需要运行 Codex、OpenCode 或 Pi，那么这些程序必须先放进镜像或快照里。如果只是想快速试一下，你可以在环境初始化时顺手安装；但如果你希望每次启动都可预测，最好将代理直接构建进镜像，避免启动时的不确定性。

Sandbox 负责安全边界

这里有必要强调：ACP 协议本身并不保证远程执行安全。真正的安全边界来自 Remote Sandbox 对文件系统、网络和进程的权限限制。换言之，Sandbox 决定了代理能碰到什么、不能碰到什么；而 ACP 只负责应用和代理之间的消息传递。两者结合，才构成可靠的远程代理环境。

在实现中，Sandbox 拥有远程环境，而 Agent provider 提供命令和配置。ACP 则用完全一致的方式，把你的应用和那个代理进程连接起来，无论你选用哪一个代理。

写在最后

利用 ACP 协议，配合 TypeScript SDK，你可以在本地应用与远程沙盒中的 AI Agent 之间建立一条稳定、持久的会话通道。通过 AML 这样的工具将代理生命周期标准化，你就能以统一的接口管理多个编程代理，真正实现可落地、可复用的 Coding Automation 流程。对于需要在云端或隔离环境中执行 AI 代码任务的团队来说，这套架构值得一试。