에이전트 클라이언트 프로토콜 · 안정적인 프로토콜 v1

귀하의 제품에 인쇄 에이전트를 추가하거나 에이전트를 편집기로 가져옵니다.

ACP는 코딩 인터페이스와 코딩 에이전트에게 프로젝트 열기, 프롬프트 교환, 진행 상황 스트리밍, 승인 요청, 작업 취소 및 동일한 세션 계속을 위한 공유 방법을 제공합니다. ADK-Rust는 해당 관계의 양면을 구현합니다.

공식 SDK 메시지 형식클라이언트 + 상담원 역할영구 세션실시간 유형 업데이트비동기 인간 승인취소수명주기 지속성

ADK-Rust ACP 아키텍처

하나의 프로토콜, 두 가지 유용한 지침.

인터페이스가 있는 프로그램은 ACP 클라이언트입니다. 코딩 작업을 수행하는 프로그램은 ACP 에이전트입니다. ADK-Rust는 그 관계의 양쪽에 앉을 수 있습니다.

01 · ADK-Rust는 ACP 클라이언트/호스트입니다.

ADK-Rust는 외부 코딩 에이전트를 사용합니다.

이 방향을 선택해

ADK 코디네이터

저장소 작업에 코딩 전문가가 필요하다고 결정합니다.

도구 호출

AcpAgentTool · 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.

방향 1 · ADK-Rust가 클라이언트입니다

ADK 에이전트가 저장소 작업을 코딩 에이전트에 위임하도록 합니다.

외부 ACP 프로세스는 ADK-Rust 내부에 명명된 도구로 나타납니다. 코디네이터는 언제 사용할지 결정하고, 프로젝트 디렉터리를 선택하고, 작업이 여러 단계에 걸쳐 진행되는 경우 컨텍스트를 유지하고, 진행 상황을 인터페이스로 스트리밍하고, 코딩 에이전트 외부에서 승인 정책을 유지할 수 있습니다.

AcpAgentTool

하나의 작업, 새로운 프로세스

ADK 에이전트가 때때로 자체 포함된 저장소 작업을 위임할 때 가장 좋습니다. 각 호출은 ACP 프로세스를 시작하고 해당 텍스트를 일반 도구 출력으로 반환합니다.

AcpToolset

여러 코딩 전문가

검토, 테스트, 마이그레이션 또는 문서화 에이전트라는 코디네이터를 지정합니다. 도구 설명은 모델이 각 작업을 올바른 프로세스로 라우팅하는 데 도움이 됩니다.

AcpSession

계속되는 대화 하나

프롬프트 전체에서 프로세스와 ACP 세션을 활성 상태로 유지합니다. 에이전트는 이미 검사한 내용을 기억하고 취소 핸들을 통해 비행 중 회전을 중지할 수 있습니다.

stream_prompt

라이브 제품 UI

하나의 결합된 문자열을 기다리는 대신 발생하는 텍스트, 생각, 도구 호출, 권한, 완료 및 오류 청크를 수신합니다.

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.

ACP 세션 설정에 MCP가 나타나는 이유

클라이언트는 하나의 코딩 세션에 도구 서버를 빌려줄 수 있습니다.

예를 들어, 편집자는 세션을 열 때 이슈 트래커 또는 저장소 검색 MCP 서버를 연결할 수 있습니다. 코딩 에이전트는 자격 증명이나 구성을 소유하지 않고도 해당 도구를 받습니다. ADK-Rust는 안정적인 ACP v1에 필요한 stdio 전송을 지원하고 제한된 핸드셰이크로 각 서버를 시작한 다음 세션과 함께 제거합니다. 선택적 HTTP 및 SSE 전송은 외부 에이전트가 광고하는 경우에만 클라이언트에서 허용됩니다.

승인은 호스트에게 속합니다

사용자와 정책이 어디에 있는지 결정하세요.

코딩 에이전트는 파일을 편집하거나, 명령을 실행하거나, 종속성을 설치하거나, 생성된 출력을 삭제해야 할 수 있습니다. ACP는 제안된 작업을 유효한 선택 메뉴와 함께 클라이언트에 다시 보냅니다. ADK-Rust는 보안 관련 세부 정보를 유지하고 기본적으로 요청을 거부합니다.

신뢰할 수 있는 로컬 워크플로의 경우 규칙은 알려진 작업을 승인할 수 있습니다. 대화형 제품의 경우 PermissionPolicy::async_custom는 데스크톱 대화 상자, 웹 승인 화면 또는 조직 정책 서비스를 기다릴 수 있습니다. 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.

방향 2 · 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.