人们与之交互的应用程序
通常是编辑器、桌面应用程序、CLI 或 ADK-Rust 协调员。它启动编码代理,打开项目会话,显示进度,并决定如何向用户提出权限问题。
ACP 为编码接口和编码代理提供了一种共享方式来打开项目、交换提示、流式传输进度、请求批准、取消工作和继续同一会话。 ADK-Rust 实现了该关系的双方。
ADK-Rust ACP 架构
具有该接口的程序是ACP客户端。执行编码工作的程序是 ACP 代理。 ADK-Rust 可以处于这种关系的任何一方。
01 · ADK-Rust 是 ACP 客户端/主机
决定存储库任务需要编码专家。
启动进程、选择工作区、保留上下文并应用权限策略。
检查代码、提出编辑建议、调用工具并流式传输其进度。
The shared ACP v1 contract
Both directions use the same message vocabulary.
initializesession/newsession/promptsession/updaterequest_permissioncancelclose · list · resume · delete02 · ADK-Rust 是 ACP 代理/服务器
拥有对话 UI 并启动 ADK-Rust 二进制文件。
协商功能、验证会话、流式传输更新并处理取消。
使用模型、Rust 工具、工作流程、会话、内存和工件来完成转弯。
一个 ACP 会话映射到一个持久的 ADK-Rust 会话。
客户选择代理实际提供的选项。
文本、想法、工具启动和工具完成流为 session/update。
稳定版 ACP v1 使用本地子进程和基于 stdio 的 JSON-RPC。
从关系开始
编码代理可以推理存储库并使用工具,但人们仍然需要一个界面,可以在其中描述工作、查看代理正在做什么、回答问题、批准敏感操作以及停止轮流。如果没有标准,每个编辑器和每个编码代理都需要针对这些基础知识进行自定义集成。
ACP 定义了缺失的对话。客户端拥有它选择提供的界面和工作环境。代理拥有编码情报。他们就会话、提示、内容、实时更新、工具调用、权限选择、取消和完成达成一致,而无需共享实现代码。
ADK-Rust支持两个实用方向。 ADK 代理可以将工作委托给外部 ACP 编码代理作为工具。借助服务器功能,编辑者可以启动 ADK-Rust 二进制文件,并通过相同的 ACP v1 合约使用其 Runner、模型、工具、会话、内存和工作流程。
通常是编辑器、桌面应用程序、CLI 或 ADK-Rust 协调员。它启动编码代理,打开项目会话,显示进度,并决定如何向用户提出权限问题。
它接收提示、有关存储库的原因、报告工具活动、在敏感操作之前询问,并在回合结束时返回停止原因。
会话具有 ID、绝对工作目录、可选的工作区根、多个提示、流式更新以及明确的关闭或恢复生命周期。
代理描述确切的工具调用并提供选择。客户端返回这些选择之一,因此应用程序(而不是代理)控制操作是否继续。
One ACP turn
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.
Editor or ADK-Rust
Coding process or ADK-Rust
initializeprotocolVersion: 1
capabilitiesWhat this agent really supports
session/newAbsolute cwd + workspace roots
session/promptTyped content blocks
session/updateText · thought · tool call
session/request_permissionChoose from offered options
permission responseAllow once · always · reject
PromptResponseend_turn · cancelled
session/cancel into the Runner cancellation token and returns a typed cancelled stop reason.方向一·ADK-Rust为客户
外部 ACP 进程作为命名工具出现在 ADK-Rust 内部。您的协调员可以决定何时使用它,选择项目目录,在工作跨越多个轮次时保留上下文,将进度传输到您的界面中,并将批准策略保留在编码代理之外。
AcpAgentTool当 ADK 代理偶尔委托独立的存储库任务时最好。每个调用都会启动一个 ACP 进程,并将其文本作为正常工具输出返回。
AcpToolset指定一名名为审核、测试、迁移或文档代理的协调员。他们的工具描述帮助模型将每个任务路由到正确的流程。
AcpSession在提示中保持进程和 ACP 会话处于活动状态。代理会记住已经检查过的内容,并且取消手柄可以停止飞行中的转弯。
stream_prompt当文本、想法、工具调用、权限、完成和错误块发生时接收它们,而不是等待一个组合字符串。
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()?;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 服务器传递到会话创建中。默认情况下未启用任何内容。只读文档工具、具有未保存缓冲区的桌面编辑器和独立的构建工作人员都可以发布不同的、准确的功能集。
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.
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.
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;它从不发明认可价值。
该请求携带会话 ID、工具调用 ID、标题、工具类型、原始输入以及代理支持的每个响应选项。
默认拒绝、使用同步规则或通过 async_custom 等待人工对话或远程策略服务。
允许和拒绝选项按照ACP的意思进行匹配,然后返回原来的不透明选项ID。伪造的身份证件将被取消。
编码代理在同一会话中接收决策,并可以继续工具调用、选择另一条路径或完成转弯。
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的代理
编辑器将 Rust 二进制文件作为 ACP 子进程启动。官方SDK拥有JSON-RPC帧、请求ID、类型化解码和stdio。会话处理程序将一个 ACP 会话映射到一个 ADK-Rust 会话,然后 Runner 将模型和工具事件作为实时 session/update 通知返回。
当您的代理具有应可从编码接口获取的特定于域的指令、Rust 工具、工作流代理、内存或内部服务时,此方向非常有用。编辑者不需要了解这些内部原理;它看到二进制文件诚实发布的功能和生命周期。
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?;{
"name": "repository-guide",
"command": "/absolute/path/to/repository-guide",
"args": [],
"env": {
"MODEL_API_KEY": "from-the-editor-secret-store"
}
}{
"jsonrpc": "2.0",
"id": 3,
"method": "session/prompt",
"params": {
"sessionId": "session-7f2a",
"prompt": [{
"type": "text",
"text": "Explain error handling in src/main.rs"
}]
}
}{"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 表面与仍需要实现的功能分开,因此编辑器或产品在集成工作开始后不会发现缺少的功能。
ACP protocol v1 · official Rust SDK 1.2 · JSON-RPC over local stdio
ImplementedInitialize, new session, prompt, live updates, tool permissions, one-shot, persistent, streaming
ImplementedCloneable handle sends session/cancel while another task awaits the prompt
ImplementedInitialize, new, prompt, update, cancel, close, list, resume, delete
ImplementedText and resource links; unsupported media types are rejected and not advertised
Implemented scopeOpt-in host traits advertise only the file and terminal operations the application implements
Implemented APITyped session configuration, required stdio server support, per-session ADK toolsets, bounded startup and cleanup
Implemented · stdioThe 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 limitationHTTP or WebSocket ACP between machines
Protocol work is evolving; stdio only互操作性门
官方的SDK客户端通过内存传输连接到ADK-Rust SDK代理,并完成初始化→新建→提示→更新→关闭→列表→恢复→关闭→删除。取消测试涵盖 ACP 会话/取消和 JSON-RPC 请求取消,然后证明会话在清理后可以接受另一个提示。权限测试包括拒绝优先菜单、不透明的 ID、捏造的选择以及等待的人为决定。单独的实时门启动真正的 stdio MCP 子级,并通过 ACP 会话使用的相同 McpToolset 发现其工具目录。
选择边界
首先询问另一边有什么。编码代理需要项目会话和交互式主机。远程业务代理需要网络任务合同。工具或数据服务需要可调用的能力合约。