Agent Client Protocol

Agent Client Protocol (ACP)

Deep Agents를 Agent Client Protocol(ACP)로 노출해 코드 에디터와 IDE에 통합하세요.

Agent Client Protocol (ACP)은 코딩 에이전트와 코드 에디터 또는 IDE 간의 통신을 표준화합니다. ACP 프로토콜을 사용하면 커스텀 딥 에이전트를 ACP 호환 클라이언트와 함께 사용할 수 있어, 코드 에디터가 프로젝트 컨텍스트를 제공하고 풍부한 업데이트를 받을 수 있습니다.

출처: 문서

본문

ACP는 에이전트-에디터 통합을 위해 설계되었습니다. 에이전트가 외부 서버가 호스팅하는 도구를 호출하게 하려면 [Model Context Protocol (MCP)](/oss/javascript/langchain/mcp/)를 참고하세요.

빠른 시작 (Quickstart)

ACP 통합 패키지를 설치하세요:

npm install deepagents-acp

yarn add deepagents-acp

pnpm add deepagents-acp

그런 다음 딥 에이전트를 ACP로 노출하세요.

이렇게 하면 stdio 모드의 ACP 서버가 시작됩니다 (stdin에서 요청을 읽고 stdout으로 응답을 씁니다). 실제로는 보통 ACP 클라이언트(예: 에디터)가 실행하는 명령으로 실행하며, 그 클라이언트가 stdio로 서버와 통신합니다.

import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "coding-assistant",
    description: "AI coding assistant with filesystem access",
  },
  workspaceRoot: process.cwd(),
});

코드를 작성하지 않고 CLI를 사용할 수도 있습니다:

npx deepagents-acp

Deep Agents ACP on npm: deepagents-acp 패키지는 딥 에이전트를 ACP로 노출하는 CLI와 프로그래밍 API를 모두 제공합니다.

클라이언트 (Clients)

딥 에이전트는 ACP 에이전트 서버를 실행할 수 있는 어디서든 작동합니다. 주목할 만한 ACP 클라이언트는:

Zed
JetBrains IDEs
Visual Studio Code (vscode-acp 경유)
Neovim (ACP 호환 플러그인 경유)

Zed

Zed 설정(~/.config/zed/settings.json Linux, ~/Library/Application Support/Zed/settings.json macOS)에 추가해 딥 에이전트를 Zed에 등록하세요:

간단한 설정 (코드 불필요):

{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",
        "command": "npx",
        "args": ["deepagents-acp"],
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-..."
        }
      }
    }
  }
}

CLI 옵션과 함께:

{
  "agent": {
    "profiles": {
      "deepagents": {
        "name": "DeepAgents",
        "command": "npx",
        "args": [
          "deepagents-acp",
          "--name", "my-assistant",
          "--skills", "./skills",
          "--debug"
        ],
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-..."
        }
      }
    }
  }
}

커스텀 서버 스크립트:

더 많은 제어를 위해 TypeScript 서버 스크립트를 만드세요:

// server.ts
import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "my-agent",
    description: "My custom coding agent",
    skills: ["./skills/"],
  },
});

그런 다음 Zed가 이를 가리키게 하세요:

{
  "agent": {
    "profiles": {
      "my-agent": {
        "name": "My Agent",
        "command": "npx",
        "args": ["tsx", "./server.ts"]
      }
    }
  }
}

Zed의 Agents 패널을 열고 Deep Agents 스레드를 시작하세요.

ACP 레지스트리

Deep Agents는 ACP Agent Registry에서 Zed와 JetBrains IDE에 원클릭 설치로 사용할 수 있습니다. ACP 클라이언트가 레지스트리를 지원하면 사용자는 수동 구성 없이 Deep Agents를 발견하고 설치할 수 있습니다.

CLI 레퍼런스

CLI는 ACP 서버를 시작하는 가장 빠른 방법입니다. 코드가 필요 없습니다 — npx deepagents-acp를 실행하고 에디터를 연결하세요.

npx deepagents-acp [options]

옵션	약어	설명
`--name <name>`	`-n`	에이전트 이름 (기본: `"deepagents"`)
`--description <desc>`	`-d`	에이전트 설명
`--model <model>`	`-m`	LLM 모델 (기본: `"claude-sonnet-4-5-20250929"`)
`--workspace <path>`	`-w`	워크스페이스 루트 디렉터리 (기본: cwd)
`--skills <paths>`	`-s`	쉼표로 구분된 스킬 경로
`--memory <paths>`		쉼표로 구분된 AGENTS.md 경로
`--debug`		stderr로 디버그 로깅 활성화
`--help`	`-h`	도움말 메시지 표시
`--version`	`-v`	버전 표시

환경 변수:

변수	설명
`ANTHROPIC_API_KEY`	Anthropic/Claude 모델용 API 키 (필수)
`OPENAI_API_KEY`	OpenAI 모델용 API 키
`DEBUG`	`"true"`로 설정하면 디버그 로깅 활성화
`WORKSPACE_ROOT`	`--workspace` 플래그의 대안

프로그래밍 API (Programmatic API)

`startServer`

서버를 한 번의 호출로 생성하고 시작하는 편의 함수:

import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "coding-assistant",
    description: "AI coding assistant with filesystem access",
  },
  workspaceRoot: process.cwd(),
});

`DeepAgentsServer`

완전한 제어를 위해 DeepAgentsServer 클래스를 직접 사용하세요:

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "google-genai:gemini-3.6-flash",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "openai:gpt-5.5",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "anthropic:claude-sonnet-5",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "openrouter:z-ai/glm-5.2",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "fireworks:accounts/fireworks/models/glm-5p2",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "baseten:zai-org/GLM-5.2",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "ollama:north-mini-code-1.0",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  serverName: "my-deepagents-acp",
  serverVersion: "1.0.0",
  workspaceRoot: process.cwd(),
  debug: true,
});

await server.start();

서버 옵션:

옵션	유형	기본값	설명
`agents`	`DeepAgentConfig \| DeepAgentConfig[]`	필수	에이전트 구성
`serverName`	`string`	`"deepagents-acp"`	ACP용 서버 이름
`serverVersion`	`string`	`"0.0.1"`	서버 버전
`workspaceRoot`	`string`	`process.cwd()`	워크스페이스 루트 디렉터리
`debug`	`boolean`	`false`	디버그 로깅 활성화

에이전트 구성:

옵션	유형	설명
`name`	`string`	고유 에이전트 이름 (필수)
`description`	`string`	에이전트 설명
`model`	`string`	LLM 모델 (기본: `"claude-sonnet-4-5-20250929"`)
`tools`	`StructuredTool[]`	커스텀 LangChain 도구
`systemPrompt`	`string`	커스텀 시스템 프롬프트
`middleware`	`AgentMiddleware[]`	Deep Agents 스택에 추가되는 커스텀 미들웨어
`backend`	`AnyBackendProtocol`	파일시스템 백엔드
`skills`	`string[]`	스킬 소스 경로
`memory`	`string[]`	메모리 소스 경로 (AGENTS.md)
`interruptOn`	`Record<string, boolean \| InterruptOnConfig>`	사용자 승인(HITL)이 필요한 도구
`commands`	`Array<{ name, description, input? }>`	커스텀 슬래시 명령

커스터마이즈 (Customization)

여러 에이전트

단일 서버에서 여러 에이전트를 노출할 수 있습니다. ACP 클라이언트는 세션을 만들 때 사용할 에이전트를 선택합니다:

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: [
    { name: "code-agent", description: "General coding" },
    { name: "reviewer", description: "Code reviews" },
  ],
});

일부 ACP 클라이언트(예: Zed)는 현재 에이전트 선택 UI를 노출하지 않습니다. 그 경우 각각 단일 에이전트를 가진 별도의 서버 인스턴스를 실행하는 것을 고려하세요.

슬래시 명령 (Slash commands)

서버는 IDE에 /plan, /agent, /ask, /clear, /status 같은 내장 슬래시 명령을 등록합니다. 에이전트별 커스텀 명령도 정의할 수 있습니다:

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "my-agent",
    commands: [
      { name: "test", description: "Run the project's test suite" },
      { name: "lint", description: "Run linter and fix issues" },
      {
        name: "deploy",
        description: "Deploy to staging",
        input: { hint: "environment (staging or production)" },
      },
    ],
  },
});

휴먼 인 더 루프 (Human-in-the-loop)

interruptOn으로 에이전트가 민감한 도구를 실행하기 전에 IDE에서 사용자 승인을 요구하게 하세요:

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "careful-agent",
    interruptOn: {
      execute: { allowedDecisions: ["approve", "edit", "reject"] },
      write_file: true,
    },
  },
});

에이전트가 보호된 도구를 호출하면 IDE가 사용자에게 작업을 허용하거나 거부할지 프롬프트하며, 세션 동안 결정을 기억하는 옵션을 제공합니다.

커스텀 도구

import { DeepAgentsServer } from "deepagents-acp";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const searchTool = tool(
  async ({ query }) => {
    return `Results for: ${query}`;
  },
  {
    name: "search",
    description: "Search the codebase",
    schema: z.object({ query: z.string() }),
  },
);

const server = new DeepAgentsServer({
  agents: {
    name: "search-agent",
    tools: [searchTool],
  },
});


await server.start();

커스텀 백엔드

import { DeepAgentsServer } from "deepagents-acp";
import { CompositeBackend, FilesystemBackend, StateBackend } from "deepagents";

const server = new DeepAgentsServer({
  agents: {
    name: "custom-agent",
    backend: new CompositeBackend(new StateBackend(), {
      "/workspace/": new FilesystemBackend({ rootDir: "./workspace" }),
    }),
  },
});

스킬과 메모리

import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "project-agent",
    description: "Agent with project-specific knowledge",
    skills: ["./skills/", "~/.deepagents/skills/"],
    memory: ["./.deepagents/AGENTS.md"],
  },
  workspaceRoot: process.cwd(),
});

프로토콜 세부 사항과 에디터 지원은 상위 ACP 문서를 참고하세요:

소개: https://agentclientprotocol.com/get-started/introduction
클라이언트/에디터: https://agentclientprotocol.com/get-started/clients

더 알아보기

이 문서를 MCP로 연결하면 Claude, VSCode 등에서 실시간 답변을 받을 수 있어요.
GitHub에서 이 페이지 편집하기 또는 이슈 제출하기.