ACP

ACP (에이전트 클라이언트 프로토콜) — ACP (Agent Client Protocol)

Agent Client Protocol을 통해 Docker Agent 에이전트를 노출해서 VS Code, IDE, 기타 개발자 도구 같은 ACP 호환 호스트와 통합해요.

출처: 문서

본문

개요 (Overview)

docker agent serve acp 명령은 stdio(표준 입력/출력)로 통신하는 ACP 서버를 시작해요. 이는 편집기, IDE, 에이전트 프로세스를 생성하는 다른 도구와의 통합에 이상적이에요 — 호스트가 Docker Agent의 stdin으로 JSON-RPC 메시지를 보내고 stdout에서 응답을 읽어요.

ACP는 ACP Go SDK 위에 구축되며 클라이언트 애플리케이션이 AI 에이전트와 상호작용하는 표준화된 방법을 제공해요.

Note ACP vs A2A vs MCP ACP는 에이전트를 호스트 애플리케이션(IDE, CLI 도구)에 stdio로 연결해요. A2A는 에이전트를 HTTP로 다른 에이전트에 연결해요. MCP는 에이전트를 다른 MCP 클라이언트의 도구로 노출해요. 통합 대상에 따라 선택하세요.

사용법 (Usage)

# Start ACP server on stdio
$ docker agent serve acp ./agent.yaml

# With a multi-agent team config
$ docker agent serve acp ./team.yaml

# From an OCI registry
$ docker agent serve acp myorg/agent:tag

# With a custom session database
$ docker agent serve acp ./agent.yaml --session-db ./my-sessions.db

동작 원리 (How It Works)

호스트 애플리케이션이 자식 프로세스로 docker agent serve acp agent.yaml 을 생성
통신은 ACP 프로토콜을 사용해 stdin/stdout으로 일어남
호스트가 사용자 메시지를 보내고, Docker Agent가 에이전트를 통해 처리
에이전트 응답, 도구 호출, 이벤트가 호스트로 스트리밍
세션은 연속성을 위해 SQLite 데이터베이스에 유지

# Conceptual flow:
Host Application
└── spawns: docker agent serve acp agent.yaml
    ├── stdin ← JSON-RPC requests from host
    └── stdout → JSON-RPC responses to host

기능 (Features)

Stdio 전송 — 네트워크 포트 불필요; 하위 프로세스 통합에 이상적
세션 유지 — SQLite 기반 세션이 프로세스 재시작을 견딤
전체 에이전트 지원 — 도구, 다중 에이전트, 모델 폴백 등 모든 Docker Agent 기능 동작
다중 에이전트 구성 — 하위 에이전트가 있는 팀 구성이 투명하게 동작
파일시스템 작업 — 에이전트가 호스트의 작업 디렉터리에 상대적으로 파일 읽기/쓰기

CLI 플래그 (CLI Flags)

docker agent serve acp <agent-file> | <registry-ref> [flags]

Flag	Default	Description
`-s, --session-db <path>`	`<data-dir>/session.db`	SQLite 세션 데이터베이스 경로
`--working-dir <path>`	current dir	에이전트가 실행되는 작업 디렉터리
`--env-from-file <file>`	(none)	`.env` 파일에서 추가 환경 변수 로드 (반복 가능)
`--models-gateway <url>`	(none)	모든 제공자 트래픽을 모델 게이트웨이 URL로 라우팅
`--code-mode-tools`	false	실행할 JavaScript 스니펫을 받는 단일 "code" toolset으로 도구 노출
`--hook-pre-tool-use <cmd>`	(none)	pre-tool-use 훅 추가 (반복 가능). Hooks 참고
`--hook-post-tool-use <cmd>`	(none)	post-tool-use 훅 추가 (반복 가능)
`--hook-session-start <cmd>`	(none)	session-start 훅 추가 (반복 가능)
`--hook-session-end <cmd>`	(none)	session-end 훅 추가 (반복 가능)
`--hook-on-user-input <cmd>`	(none)	on-user-input 훅 추가 (반복 가능)
`--hook-stop <cmd>`	(none)	모델이 응답을 마칠 때 발동하는 stop 훅 추가 (반복 가능)

통합 예제 (Integration Example)

호스트 애플리케이션은 Docker Agent를 하위 프로세스로 생성하고 ACP 프로토콜로 통신해요:

// Pseudocode for an IDE extension
const child = spawn("docker", ["agent", "serve", "acp", "./agent.yaml"]);

// Send a message to the agent
child.stdin.write(
  JSON.stringify({
    jsonrpc: "2.0",
    method: "agent/run",
    params: { message: "Explain this code" },
  }),
);

// Read responses
child.stdout.on("data", (data) => {
  const response = JSON.parse(data);
  // Handle agent response, tool calls, etc.
});

Tip ACP를 언제 쓸까 IDE 통합, 편집기 플러그인, 또는 Docker Agent 에이전트를 하위 프로세스로 임베드하려는 어떤 도구를 만들 때 ACP를 사용하세요. HTTP 기반 통합은 API Server를 사용하세요.

Note 참고 (See also) HTTP 기반 에이전트 접근은 API Server 참고. 에이전트 간 통신은 A2A Protocol 참고. 에이전트를 MCP 도구로 노출은 MCP Mode 참고.

ACP