> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Agent 클라이언트 프로토콜

마스트라는 다음을 지원합니다.[Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction)Mastra Agent에서 ACP 호환 코딩 Agent를 실행하기 위한 것입니다. 사용`@mastra/acp`코딩 Agent 프로세스를 Mastra Tool 또는 하위 Agent로 래핑합니다.

ACP는 Claude Code, Amp, Codex 또는 표준 입력 및 출력을 통해 ACP를 구현하는 기타 실행 파일과 같은 코딩 Agent에 유용합니다.

## ACP를 사용해야 하는 경우

- Mastra Agent는 코드 검사, 편집 또는 저장소 작업을 외부 코딩 Agent에 위임해야 합니다.
- ACP 호환 Agent 프로세스는 세션 컨텍스트를 유지할 수 있도록 호출 전반에 걸쳐 활성 상태를 유지해야 합니다.
- 상위 Agent에는 작업이 실행되는 동안 코딩 Agent의 실시간 출력이 필요합니다.
- ACP 호환 Agent는 파일을 읽거나 쓰거나 작업을 실행하기 전에 권한 Prompt가 필요합니다.
- 파일 액세스는 직접적인 프로세스 전용 파일 액세스 대신 Mastra의 작업 공간 추상화를 거쳐야 합니다.

## ACP 작동 방식

`@mastra/acp`구성된 ACP Agent 명령을 하위 프로세스로 시작하고 표준 입력 및 출력을 통해 줄 바꿈으로 구분된 JSON을 사용하여 통신합니다.

흐름은 다음과 같습니다.

1. `command`, `args` 및 선택적 연결 설정을 구성합니다.
2. `@mastra/acp`는 처음 사용할 때 ACP Agent 프로세스를 생성합니다.
3. 클라이언트가 ACP `initialize` 및 `session/new` 요청을 보냅니다.
4. Mastra는 사용자 작업을 `session/prompt`를 통해 ACP Agent에 보냅니다.
5. ACP Agent는 세션 업데이트 및 메시지 청크를 Mastra로 다시 스트리밍합니다.
6. Mastra는 버퍼링된 출력을 반환하거나 스트리밍 청크를 내보내거나 권한 입력을 처리합니다.
7. `persistSession`이 `false`인 경우 Prompt가 처리된 후 ACP 연결이 프로세스를 중지합니다. 기본적으로 `AcpAgent`는 호출 간에 재사용 가능한 프로세스를 계속 실행할 수 있습니다. 실행 중에 ACP 클라이언트는 권한 요청과 파일 작업도 처리합니다. 파일 읽기 및 쓰기는 Mastra `Workspace`를 통해 이루어지므로 ACP Agent는 사용자가 제공한 Workspace 내에서 작동합니다.

## 시작하기

이미 `@mastra/core`를 사용하는 프로젝트에 `@mastra/acp`를 설치합니다. 이 패키지를 사용하려면 `@mastra/core` 버전 `1.34.0` 이상이 필요합니다.

**npm**:

```bash
npm install @mastra/acp
```

**pnpm**:

```bash
pnpm add @mastra/acp
```

**Yarn**:

```bash
yarn add @mastra/acp
```

**Bun**:

```bash
bun add @mastra/acp
```

`@mastra/acp`두 개의 API를 내보냅니다.

- [`createACPTool()`](https://mastra.zisheng.pro/ko/reference/acp/create-acp-tool): ACP Agent에 `task` 문자열을 보내고 `output` 문자열을 반환하는 Mastra Tool을 만듭니다.
- [`AcpAgent`](https://mastra.zisheng.pro/ko/reference/acp/acp-agent): `generate()` 및 `stream()`을 지원하도록 ACP Agent를 Mastra 하위 Agent로 래핑합니다.

## ACP를 하위 Agent로 사용

상위 Mastra Agent가 ACP 호환 코딩 Agent에 하위 Agent로 직접 작업을 위임해야 하는 경우 `AcpAgent`를 사용합니다.

```typescript
import { AcpAgent } from '@mastra/acp'
import { Agent } from '@mastra/core/agent'

const codeAgent = new AcpAgent({
  id: 'code-agent',
  name: 'Code Agent',
  description: 'An ACP-compatible coding agent that can inspect and edit files',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
})

export const codeSupervisor = new Agent({
  id: 'code-supervisor',
  name: 'Code Supervisor',
  instructions: 'Delegate code editing tasks to the code-agent subagent.',
  model: 'openai/gpt-5.6-sol',
  agents: {
    codeAgent,
  },
})
```

모든 옵션, 메서드 및 구성은 [AcpAgent 참조](https://mastra.zisheng.pro/ko/reference/acp/acp-agent)를 확인하세요.

## ACP를 Tool로 사용

상위 Mastra Agent가 ACP Agent를 Tool로 호출할 시점을 결정해야 하는 경우 `createACPTool()`을 사용합니다.

```typescript
import { createACPTool } from '@mastra/acp'
import { Agent } from '@mastra/core/agent'

const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent to inspect and edit code',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
})

export const codeSupervisor = new Agent({
  id: 'code-supervisor',
  name: 'Code Supervisor',
  instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
  model: 'openai/gpt-5.6-sol',
  tools: {
    codeAgentTool,
  },
})
```

모든 옵션 및 구성은 [createACPTool() 참조](https://mastra.zisheng.pro/ko/reference/acp/create-acp-tool)를 확인하세요.

## Model 선택

ACP Agent는 선택 가능한 Model을 노출할 수 있습니다. 세션 생성 후 Model을 선택하려면 ACP 구성에 `model`을 전달하고, 런타임에 Model을 관리하려면 `AcpAgent.getAvailableModels()` 및 `AcpAgent.setModel()`을 사용합니다. 예제는 [AcpAgent Model 관리 메서드](https://mastra.zisheng.pro/ko/reference/acp/acp-agent)를 확인하세요.

## 세션 수명주기

`AcpAgent`는 처음 사용할 때 구성된 명령을 시작하고 ACP 세션을 생성합니다. 기본적으로 `persistSession`은 `true`이므로 하위 프로세스가 호출 간에 계속 실행됩니다. 각 Prompt를 격리된 프로세스에서 실행해야 하는 경우 `persistSession: false`로 설정합니다. 자세한 내용은 [AcpAgent 세션 수명 주기](https://mastra.zisheng.pro/ko/reference/acp/acp-agent) 섹션을 확인하세요.

## 권한 처리

ACP Agent는 계속 진행하기 전에 클라이언트에 권한 옵션을 선택하도록 요청할 수 있습니다. 기본적으로 `@mastra/acp`는 ACP Agent가 반환한 첫 번째 옵션을 선택합니다. 사용자 지정 권한 동작이 필요한 경우 `onPermissionRequest`를 전달합니다. 전체 예제는 [createACPTool() 권한 처리](https://mastra.zisheng.pro/ko/reference/acp/create-acp-tool) 섹션을 확인하세요.

## 작업공간 통합

ACP 파일 작업은 Mastra의 Workspace 추상화를 거칩니다. `AcpAgent`는 `workspace` 옵션을 사용할 수 있으며, `createACPTool()`은 Tool 실행 컨텍스트에 현재 Mastra Workspace가 있으면 이를 사용합니다. Workspace가 없으면 `@mastra/acp`는 `cwd` 또는 `process.cwd()`에서 `LocalFilesystem`으로 지원되는 `Workspace`를 대신 사용합니다. 사용자 지정 Workspace 예제는 [AcpAgent Workspace 통합](https://mastra.zisheng.pro/ko/reference/acp/acp-agent) 섹션을 확인하세요.

## 관련된

- [AcpAgent 참조](https://mastra.zisheng.pro/ko/reference/acp/acp-agent)
- [createACPTool() 참조](https://mastra.zisheng.pro/ko/reference/acp/create-acp-tool)
- [Agent 참조](https://mastra.zisheng.pro/ko/reference/agents/agent)
- [하위 Agent](https://mastra.zisheng.pro/ko/docs/capabilities/subagents)
- [Agent 클라이언트 프로토콜 소개](https://agentclientprotocol.com/overview/introduction)
- [Agent 클라이언트 프로토콜 스키마](https://agentclientprotocol.com/protocol/schema)