代理客户端协议·稳定协议v1

将编码剂引入您的产品中,或者将 你的代理人进入编辑器。

ACP 为编码接口和编码代理提供了一种共享方式来打开项目、交换提示、流式传输进度、请求批准、取消工作和继续同一会话。 ADK-Rust 实现了该关系的双方。

官方 SDK 消息格式客户+代理角色持续会话实时输入更新异步人工批准取消生命周期持久化

ADK-Rust ACP 架构

一份协议,两个有用的方向。

具有该接口的程序是ACP客户端。执行编码工作的程序是 ACP 代理。 ADK-Rust 可以处于这种关系的任何一方。

01 · ADK-Rust 是 ACP 客户端/主机

ADK-Rust使用外部编码代理

选择这个方向

ADK协调员

决定存储库任务需要编码专家。

工具调用

AcpAgent工具·AcpSession

启动进程、选择工作区、保留上下文并应用权限策略。

ACP v1·stdio

外部ACP代理

检查代码、提出编辑建议、调用工具并流式传输其进度。

The shared ACP v1 contract

Both directions use the same message vocabulary.

initializesession/newsession/promptsession/updaterequest_permissioncancelclose · list · resume · delete

02 · ADK-Rust 是 ACP 代理/服务器

编辑器使用 ADK-Rust 代理

选择这个方向

编辑器或ACP客户端

拥有对话 UI 并启动 ADK-Rust 二进制文件。

ACP v1·stdio

官方 SDK + 会话处理程序

协商功能、验证会话、流式传输更新并处理取消。

类型调用

Runner + ADK代理

使用模型、Rust 工具、工作流程、会话、内存和工件来完成转弯。

会话服务

一个 ACP 会话映射到一个持久的 ADK-Rust 会话。

权限边界

客户选择代理实际提供的选项。

键入更新

文本、想法、工具启动和工具完成流为 session/update。

过程边界

稳定版 ACP v1 使用本地子进程和基于 stdio 的 JSON-RPC。

ACP 不会将编辑器和编码代理合并到一个应用程序中。它为他们提供了共享会话合同,而每一方都保留自己的接口、运行时、工具和安全责任。

从关系开始

ACP解决什么问题?

编码代理可以推理存储库并使用工具,但人们仍然需要一个界面,可以在其中描述工作、查看代理正在做什么、回答问题、批准敏感操作以及停止轮流。如果没有标准,每个编辑器和每个编码代理都需要针对这些基础知识进行自定义集成。

ACP 定义了缺失的对话。客户端拥有它选择提供的界面和工作环境。代理拥有编码情报。他们就会话、提示、内容、实时更新、工具调用、权限选择、取消和完成达成一致,而无需共享实现代码。

ADK-Rust支持两个实用方向。 ADK 代理可以将工作委托给外部 ACP 编码代理作为工具。借助服务器功能,编辑者可以启动 ADK-Rust 二进制文件,并通过相同的 ACP v1 合约使用其 Runner、模型、工具、会话、内存和工作流程。

客户端/主机

人们与之交互的应用程序

通常是编辑器、桌面应用程序、CLI 或 ADK-Rust 协调员。它启动编码代理,打开项目会话,显示进度,并决定如何向用户提出权限问题。

ACP 代理

执行编码工作的进程

它接收提示、有关存储库的原因、报告工具活动、在敏感操作之前询问,并在回合结束时返回停止原因。

会议

共同的工作对话

会话具有 ID、绝对工作目录、可选的工作区根、多个提示、流式更新以及明确的关闭或恢复生命周期。

许可

行动时的决定

代理描述确切的工具调用并提供选择。客户端返回这些选择之一,因此应用程序(而不是代理)控制操作是否继续。

One ACP turn

The interface stays responsive while the agent works.

Read from top to bottom. Initialization establishes the contract once. A session then carries several prompts, live updates, approval questions, cancellation, and a final stop reason.

Client / host

Editor or ADK-Rust

ACP agent

Coding process or ADK-Rust

initialize

protocolVersion: 1

capabilities

What this agent really supports

session/new

Absolute cwd + workspace roots

session/prompt

Typed content blocks

session/update

Text · thought · tool call

session/request_permission

Choose from offered options

permission response

Allow once · always · reject

PromptResponse

end_turn · cancelled

Cancellation is part of the conversation. ADK-Rust forwards session/cancel into the Runner cancellation token and returns a typed cancelled stop reason.

方向一·ADK-Rust为客户

让 ADK 代理将存储库委托给编码代理。

外部 ACP 进程作为命名工具出现在 ADK-Rust 内部。您的协调员可以决定何时使用它,选择项目目录,在工作跨越多个轮次时保留上下文,将进度传输到您的界面中,并将批准策略保留在编码代理之外。

AcpAgentTool

一项任务,全新流程

当 ADK 代理偶尔委托独立的存储库任务时最好。每个调用都会启动一个 ACP 进程,并将其文本作为正常工具输出返回。

AcpToolset

多名编码专家

指定一名名为审核、测试、迁移或文档代理的协调员。他们的工具描述帮助模型将每个任务路由到正确的流程。

AcpSession

一场持续的对话

在提示中保持进程和 ACP 会话处于活动状态。代理会记住已经检查过的内容,并且取消手柄可以停止飞行中的转弯。

stream_prompt

实时产品用户界面

当文本、想法、工具调用、权限、完成和错误块发生时接收它们,而不是等待一个组合字符串。

orchestrator.rs一击授权
use adk_acp::{AcpAgentTool, PermissionPolicy};

  let coder = AcpAgentTool::new("my-coding-agent --acp")
      .name("repository_coder")
      .description("Inspect and improve this Rust project")
      .working_dir("/absolute/path/to/project")
      .permission_policy(PermissionPolicy::DenyAll);

  let coordinator = LlmAgentBuilder::new("coordinator")
      .model(model)
      .tool(Arc::new(coder))
      .build()?;
session.rs持续+可取消
let mut session = AcpSession::start(
      AcpAgentConfig::new("my-coding-agent --acp")
          .working_dir("/absolute/path/to/project"),
      Arc::new(permission_policy),
  ).await?;

  let cancel = session.cancellation_handle()?;
  tokio::spawn(async move {
      shutdown.cancelled().await;
      cancel.cancel().await
  });

  let result = session
      .prompt("Trace the failing test and propose a fix")
      .await?;

客户可以提供工作环境

选择编码代理可以达到的范围。

ACP 不假设编码代理可以读取您的磁盘或直接运行命令。客户端声明它准备提供的服务,处理每个请求,并将安全规则保持在产品和用户附近。

ADK-Rust 现在公开类型化文件和终端主机接口,并将客户端提供的 MCP 服务器传递到会话创建中。默认情况下未启用任何内容。只读文档工具、具有未保存缓冲区的桌面编辑器和独立的构建工作人员都可以发布不同的、准确的功能集。

AcpFileSystem

Files from the real workspace

Your editor or application decides how reads and writes work. It can return an unsaved buffer, enforce approved roots, reject a symlink escape, or make the session read-only.

AcpTerminal

Managed command execution

The coding agent can start a command, collect output, wait, stop it, and release it through the client. Terminal support stays disabled until the host implements the complete lifecycle.

MCP over stdio

Tools supplied for this session

Attach an MCP server when the ACP session opens. ADK-Rust starts it inside the selected project, exposes its tools only to that session, and cancels it when the session closes.

为什么 MCP 出现在 ACP 会话设置中

客户端可以将工具服务器借给一次编码会话。

例如,编辑者可以在打开会话时附加其问题跟踪器或存储库搜索 MCP 服务器。编码代理接收这些工具,但不拥有其凭证或配置。 ADK-Rust 支持稳定的 ACP v1 所需的 stdio 传输,通过有界握手启动每个服务器,并通过会话将其删除。仅当外部代理通告可选的 HTTP 和 SSE 传输时,客户端才会接受它们。

审批权归主办方所有

决定用户和策略所在的位置。

编码代理可能需要编辑文件、执行命令、安装依赖项或删除生成的输出。 ACP 将建议的操作连同有效选择的菜单发送回客户端。 ADK-Rust 保留与安全相关的详细信息并默认拒绝请求。

对于受信任的本地工作流程,规则可以批准已知操作。对于交互式产品,PermissionPolicy::async_custom 可以等待桌面对话框、Web 审批屏幕或组织策略服务。 ADK-Rust 返回代理提供的确切的不透明选项 ID;它从不发明认可价值。

01

代理描述操作

该请求携带会话 ID、工具调用 ID、标题、工具类型、原始输入以及代理支持的每个响应选项。

02

您的申请适用政策

默认拒绝、使用同步规则或通过 async_custom 等待人工对话或远程策略服务。

03

ADK-Rust 选择实数选项

允许和拒绝选项按照ACP的意思进行匹配,然后返回原来的不透明选项ID。伪造的身份证件将被取消。

04

代理继续或停止

编码代理在同一会话中接收决策,并可以继续工具调用、选择另一条路径或完成转弯。

permissions.rs异步人工批准
let policy = PermissionPolicy::async_custom(|request| async move {
      let choice = approval_ui.ask(ApprovalPrompt {
          title: request.title,
          kind: request.kind,
          input: request.raw_input,
          options: request.options,
      }).await;

      match choice {
          Approval::Once => PermissionDecision::AllowOnce,
          Approval::Always => PermissionDecision::AllowAlways,
          Approval::Reject => PermissionDecision::Deny,
      }
  });

项目目录是上下文,而不是沙箱。

ACP 告诉双方哪些项目和附加根属于该会话。它不会创建操作系统安全边界。如果编码过程必须与机器的其余部分隔离,请通过 adk-sandbox、容器或其他流程策略。

Keep credentials in the process environment or the client's secret store. Protocol stdout must contain only ACP JSON-RPC messages.

方向二·ADK-Rust是ACP的代理

向编辑器公开完整的 ADK-Rust 运行时。

编辑器将 Rust 二进制文件作为 ACP 子进程启动。官方SDK拥有JSON-RPC帧、请求ID、类型化解码和stdio。会话处理程序将一个 ACP 会话映射到一个 ADK-Rust 会话,然后 Runner 将模型和工具事件作为实时 session/update 通知返回。

当您的代理具有应可从编码接口获取的特定于域的指令、Rust 工具、工作流代理、内存或内部服务时,此方向非常有用。编辑者不需要了解这些内部原理;它看到二进制文件诚实发布的功能和生命周期。

main.rs揭露特工
use adk_acp::server::{
      AcpServer, AcpServerConfigBuilder
  };

  let config = AcpServerConfigBuilder::new()
      .agent(Arc::new(repository_agent))
      .session_service(Arc::new(session_service))
      .agent_name("repository-guide")
      .agent_description("Explains and improves this workspace")
      .max_sessions(16)
      .build()?;

  let server = AcpServer::run(config).await?;
  server.wait().await?;
acp-agent.json编辑器进程配置
{
    "name": "repository-guide",
    "command": "/absolute/path/to/repository-guide",
    "args": [],
    "env": {
      "MODEL_API_KEY": "from-the-editor-secret-store"
    }
  }
session-prompt.json请求
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "session/prompt",
    "params": {
      "sessionId": "session-7f2a",
      "prompt": [{
        "type": "text",
        "text": "Explain error handling in src/main.rs"
      }]
    }
  }
stdout.jsonl实时更新+最终回应
{"jsonrpc":"2.0","method":"session/update","params":{
    "sessionId":"session-7f2a",
    "update":{"sessionUpdate":"agent_message_chunk","content":{
      "type":"text","text":"The entry point uses..."
    }}
  }}
  {"jsonrpc":"2.0","id":3,"result":{
    "stopReason":"end_turn"
  }}

验证范围

在设计集成之前准确了解已准备就绪的内容。

ADK-Rust 现在使用官方 agent-client-protocol 箱子来扮演这两个角色。该表将可互操作的 v1 表面与仍需要实现的功能分开,因此编辑器或产品在集成工作开始后不会发现缺少的功能。

Protocol and transport

ACP protocol v1 · official Rust SDK 1.2 · JSON-RPC over local stdio

Implemented

ADK-Rust as client

Initialize, new session, prompt, live updates, tool permissions, one-shot, persistent, streaming

Implemented

Client cancellation

Cloneable handle sends session/cancel while another task awaits the prompt

Implemented

ADK-Rust as agent

Initialize, new, prompt, update, cancel, close, list, resume, delete

Implemented

Prompt content

Text and resource links; unsupported media types are rejected and not advertised

Implemented scope

Client filesystem / terminal callbacks

Opt-in host traits advertise only the file and terminal operations the application implements

Implemented API

Client-supplied MCP servers

Typed session configuration, required stdio server support, per-session ADK toolsets, bounded startup and cleanup

Implemented · stdio

ADK tool approval → ACP

The runtime can await an exact-call decision; the server bridge is held back because the official SDK currently loses the outer prompt response in the nested-request test

SDK limitation

Remote transport

HTTP or WebSocket ACP between machines

Protocol work is evolving; stdio only

互操作性门

作为对话进行测试,而不是作为断开连接的 JSON 进行测试。

官方的SDK客户端通过内存传输连接到ADK-Rust SDK代理,并完成初始化→新建→提示→更新→关闭→列表→恢复→关闭→删除。取消测试涵盖 ACP 会话/取消和 JSON-RPC 请求取消,然后证明会话在清理后可以接受另一个提示。权限测试包括拒绝优先菜单、不透明的 ID、捏造的选择以及等待的人为决定。单独的实时门启动真正的 stdio MCP 子级,并通过 ACP 会话使用的相同 McpToolset 发现其工具目录。

根据您需要的角色进行构建

添加编码专家,或者在开发人员已经工作的地方提供您的 ADK 代理。

Start with stdio, one absolute workspace, and DenyAll. Add a custom approval experience, persistent sessions, and stronger process isolation as the product's trust boundary becomes clear.