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

# AcpAgent 클래스

그만큼`AcpAgent`클래스는 ACP(Agent 클라이언트 프로토콜) 호환 코딩 Agent를 Mastra 하위 Agent로 래핑합니다. 상위 Mastra Agent가 저장소 검사 및 코드 편집을 위임해야 할 때 사용하세요. 또한 다른 ACP 지원 작업을 하위 Agent에 위임할 수도 있습니다.

대신 상위 Agent가 ACP Agent를 Tool로 호출하도록 하려면 다음을 사용하세요.[`createACPTool()`](https://mastra.zisheng.pro/ko/reference/acp/create-acp-tool).

## 사용예

상위 Agent에 ACP 호환 코딩 Agent를 등록합니다.`agents` map:

```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,
  },
})
```

Claude Code의 경우 ACP 지원은 `@agentclientprotocol/claude-agent-acp` 브리지 패키지를 통해 제공됩니다. 브리지를 실행하도록 ACP Agent 명령을 구성한 다음, 세션 생성 후 Claude Model을 선택하세요:

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

export const claudeCodeAgent = new AcpAgent({
  id: 'claude-code-agent',
  name: 'Claude Code Agent',
  description: 'Use Claude Code through ACP.',
  command: 'npx',
  args: ['@agentclientprotocol/claude-agent-acp'],
  cwd: process.cwd(),
  model: 'claude-sonnet-4-6',
})
```

## 생성자 매개변수

**id** (`string`): 하위 Agent의 고유 식별자입니다.

**name** (`string`): Agent 위임 중에 사용되는 표시 이름입니다. 기본값은 id입니다.

**description** (`string`): Model이 이 하위 Agent에 위임할 수 있을 때 표시되는 설명입니다.

**command** (`string`): 실행할 ACP Agent 실행 파일입니다.

**args** (`string[]`): ACP Agent 실행 파일에 전달되는 인수입니다. (Default: `[]`)

**env** (`Record<string, string>`): ACP 프로세스를 생성할 때 현재 프로세스 환경과 병합할 환경 변수입니다.

**cwd** (`string`): ACP 프로세스 및 ACP 세션의 작업 디렉터리입니다. 기본 로컬 파일 시스템 기준 경로로도 사용됩니다. (Default: `process.cwd()`)

**session** (`Partial<NewSessionRequest>`): ACP 세션 생성 옵션입니다. 기본값은 cwd 또는 process.cwd()와 빈 MCP 서버 목록입니다.

**initialize** (`Partial<InitializeRequest>`): ACP 초기화 옵션입니다. 기본값은 Mastra 클라이언트 정보, 현재 ACP 프로토콜 버전, 읽기/쓰기 파일 시스템 기능입니다.

**authMethodId** (`string`): 초기화 후 세션 생성 전에 호출할 ACP 인증 방법 ID입니다.

**persistSession** (`boolean`): 각 Prompt 후에도 ACP 프로세스와 세션을 유지할지 여부입니다. 각 Prompt가 완료된 후 프로세스를 중지하려면 false로 설정하세요. (Default: `true`)

**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): ACP Agent가 권한을 요청할 때 호출되는 콜백입니다. 기본적으로 첫 번째 권한 옵션을 선택하며, 사용 가능한 옵션이 없으면 취소합니다.

**createClient** (`(defaultClient: Client) => Client`): Agent 요청에 응답하는 데 사용되는 ACP 클라이언트를 사용자 지정합니다. 래핑하거나 확장할 수 있도록 기본 클라이언트를 전달받습니다. 예를 들어 extMethod 및 extNotification 핸들러를 추가할 수 있습니다. 확장 메서드를 참조하세요.

**workspace** (`Workspace`): ACP 파일 읽기 및 쓰기 요청에 사용되는 Workspace입니다. 기본값은 cwd 또는 process.cwd()의 LocalFilesystem을 기반으로 하는 Workspace입니다.

**model** (`ModelId`): ACP session/set\_model 메서드를 사용하여 ACP 세션 생성 후 선택할 Model ID입니다.

## 속성

**id** (`TId`): 생성자 옵션에서 가져온 읽기 전용 하위 Agent 식별자입니다.

**name** (`string`): 이 하위 Agent의 읽기 전용 표시 이름입니다.

**description** (`string`): 상위 Agent가 이 하위 Agent에 위임할 수 있을 때 표시되는 읽기 전용 설명입니다.

**connection** (`ACPConnection`): Agent 프로세스 시작, 세션 생성, Prompt 전송, 업데이트 스트리밍 및 Model 관리에 사용되는 읽기 전용 ACP 연결입니다.

## 행동 양식

### 세대

#### `generate(messages, options?)`

ACP Agent에 Prompt를 보내고, ACP 응답의 텍스트 청크를 버퍼링하고, Mastra 하위 Agent 생성 결과를 반환합니다.

```typescript
const result = await codeAgent.generate('Inspect the repository and summarize the test setup')

console.log(result.text)
```

#### `stream(messages, options?)`

ACP Agent에 Prompt를 보내고 Mastra 하위 Agent 스트림 결과를 반환합니다. ACP `agent_message_chunk` 업데이트는 Mastra `text-delta` 청크로 내보내집니다.

```typescript
const result = await codeAgent.stream('Refactor the selected module and explain each change')

for await (const chunk of result.fullStream) {
  if (chunk.type === 'text-delta') {
    process.stdout.write(chunk.payload.text)
  }
}
```

`resumeGenerate()`와 `resumeStream()`은 지원되지 않으며 호출하면 오류가 발생합니다.

### Model 관리

#### `getAvailableModels()`

필요한 경우 ACP 프로세스를 시작하고 ACP 세션에서 광고한 Model 목록을 반환합니다.

```typescript
const models = await codeAgent.getAvailableModels()
// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]
```

#### `setModel(modelId)`

활성 ACP 세션에 대한 Model을 선택합니다. ACP Agent가 사용 가능한 Model을 광고하는 경우 Model ID는 해당 Model 중 하나와 일치해야 합니다.

```typescript
await codeAgent.setModel('claude-sonnet-4-6')
```

## 세션 수명주기

`AcpAgent`는 처음 사용할 때 구성된 `command`를 시작하고 ACP 클라이언트를 초기화합니다. 그런 다음 ACP 세션을 생성합니다. 기본적으로 `persistSession`은 `true`이므로 `generate()`, `stream()`, `getAvailableModels()`, `setModel()` 호출 간에 프로세스와 세션이 유지됩니다. 각 Prompt를 새로운 ACP 프로세스에서 실행하려면 `persistSession: false`를 설정하세요:

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

export const codeAgent = new AcpAgent({
  id: 'code-agent',
  description: 'Run one isolated ACP coding task',
  command: 'acp-agent',
  args: ['--stdio'],
  cwd: process.cwd(),
  persistSession: false,
})
```

`persistSession: false`를 사용하면 각 Prompt가 완료된 후 `@mastra/acp`가 ACP 프로세스를 중지합니다.

## 작업공간 통합

ACP 파일 작업은 Mastra의 `Workspace` 추상화를 통해 수행됩니다. `workspace`를 전달하지 않으면 `@mastra/acp`가 `LocalFilesystem`을 기반으로 하는 `Workspace`를 생성하고 `cwd` 또는 `process.cwd()`를 파일 시스템 기준 경로로 사용합니다. ACP Agent가 특정 파일 시스템 구현을 통해 읽고 써야 한다면 사용자 지정 `Workspace`를 전달하세요:

```typescript
import { AcpAgent } from '@mastra/acp'
import { LocalFilesystem, Workspace } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: process.cwd(),
  }),
})

export const codeAgent = new AcpAgent({
  id: 'code-agent',
  description: 'Run coding tasks in a controlled workspace',
  command: 'acp-agent',
  args: ['--stdio'],
  workspace,
})
```

ACP 프로세스는 한 디렉터리에서 시작하지만 파일 작업에는 명시적으로 구성된 Workspace 루트를 사용해야 한다면 `cwd`와 `workspace`를 함께 사용하세요.

## 권한 처리

ACP Agent는 계속 진행하기 전에 클라이언트에 권한 옵션을 선택하도록 요청할 수 있습니다. 기본적으로 `AcpAgent`는 ACP Agent가 반환한 첫 번째 옵션을 선택하며, 사용 가능한 옵션이 없으면 취소합니다. 요청을 검사하고 자체 권한 응답을 반환하려면 `onPermissionRequest`를 전달하세요:

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

export const codeAgent = new AcpAgent({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent',
  command: 'acp-agent',
  args: ['--stdio'],
  async onPermissionRequest(request) {
    const allowOption = request.options.find(option => option.name === 'Allow')

    if (!allowOption) {
      return { outcome: { outcome: 'cancelled' } }
    }

    return {
      outcome: {
        outcome: 'selected',
        optionId: allowOption.optionId,
      },
    }
  },
})
```

이 콜백을 사용하여 로컬 정책을 시행하거나 권한 제목을 검사하세요. 또한 결정을 자체 승인 흐름으로 라우팅할 수도 있습니다.

## 관련된

- [Agent 클라이언트 프로토콜 문서](https://mastra.zisheng.pro/ko/docs/agents/acp)
- [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)