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

# 생성ACPTool()

그만큼`createACPTool()`함수는 다음을 보내는 Mastra Tool을 생성합니다.`task`문자열을 ACP(Agent 클라이언트 프로토콜) 호환 코딩 Agent에 전송하고 최종 ACP 응답을 다음과 같이 반환합니다.`output`. 상위 Agent가 ACP Agent를 Tool로 호출할 시기를 결정해야 할 때 사용하십시오.

대신 ACP Agent를 Mastra 하위 Agent로 등록하려면[`AcpAgent` class](https://mastra.zisheng.pro/ko/reference/acp/acp-agent).

## 사용예

코드 편집 Tool을 만들고 상위 Agent에 등록합니다.

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

## 매개변수

**id** (`string`): Mastra Tool의 고유 식별자입니다.

**description** (`string`): Model이 이 Tool을 호출할 수 있을 때 표시되는 설명입니다.

**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`): Tool 실행을 위해 생성된 ACP 연결이 Prompt 후 연결을 해제할지 여부입니다. 각 Prompt가 완료된 후 프로세스를 중지하려면 false로 설정하세요. (Default: `true`)

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

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

**workspace** (`Workspace`): 공유 ACP 연결 옵션의 Workspace 옵션입니다. Tool 실행 중 사용 가능한 경우 createACPTool()은 실행 컨텍스트의 현재 Mastra Workspace를 전달합니다. 그렇지 않으면 ACP 연결은 로컬 파일 시스템 Workspace를 대신 사용합니다. 명시적인 Workspace 인스턴스를 제공해야 한다면 AcpAgent를 사용하세요.

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

## 입력 스키마

**task** (`string`): ACP Agent에 보낼 작업입니다.

## 출력 스키마

**output** (`string`): ACP Agent가 반환한 최종 텍스트 출력입니다.

## 일시중단 및 재개 스키마

`createACPTool()`은 권한 요청 페이로드의 일시 중지 및 재개 스키마를 정의합니다. 권한 결정은 `onPermissionRequest`를 통해 반환됩니다. 기본적으로 `@mastra/acp`는 ACP Agent가 반환한 첫 번째 옵션을 선택하며, 사용 가능한 옵션이 없으면 취소합니다.

### 페이로드 일시중단

**permissionRequest** (`{ title: string; options: { optionId: string; name: string }[] }`): ACP Agent가 반환한 권한 요청 제목 및 선택 가능한 옵션입니다.

### 페이로드 재개

**optionId** (`string`): outcome: "selected"로 재개할 때 선택할 권한 옵션 ID입니다.

**outcome** (`"selected" | "cancelled"`): ACP 요청을 계속하거나 취소하는 데 사용되는 권한 결정입니다.

## 세션 수명주기

각 Tool 실행은 ACP 연결을 생성하고 구성된 `command`를 시작합니다. `task`를 ACP `session/prompt`로 보내기 전에 ACP 클라이언트를 초기화하고 ACP 세션을 생성합니다. 기본적으로 Tool 실행 중 생성되는 ACP 연결의 `persistSession`은 `true`입니다. 해당 Prompt가 완료되는 즉시 ACP 프로세스를 중지해야 한다면 `persistSession: false`를 설정하세요. 여러 호출에서 명시적으로 세션 수명 주기를 제어할 수 있는 재사용 가능한 ACP 하위 Agent 인스턴스가 필요하다면 [`AcpAgent`](https://mastra.zisheng.pro/ko/reference/acp/acp-agent)를 사용하세요.

## 권한 처리

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

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

export const codeAgentTool = createACPTool({
  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,
      },
    }
  },
})
```

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

## 확장 방법

일부 ACP Agent는 표준 ACP 요청 세트 외부에서 클라이언트의 사용자 정의 확장 메소드를 호출합니다. 기본 클라이언트는 "메소드를 찾을 수 없음" 오류와 함께 알 수 없는 메서드를 거부하며, 이로 인해 Agent의 차례가 중단될 수 있습니다.

기본 클라이언트를 확장하거나 교체하려면 `createClient`를 전달하세요. 콜백은 기본 클라이언트를 전달받아 연결에 사용할 클라이언트를 반환합니다:

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

export const codeAgentTool = createACPTool({
  id: 'code-agent',
  description: 'Use an ACP-compatible coding agent',
  command: 'acp-agent',
  args: ['--stdio'],
  createClient: defaultClient =>
    Object.assign(defaultClient, {
      async extMethod(method: string, params: Record<string, unknown>) {
        return {}
      },
      async extNotification(method: string, params: Record<string, unknown>) {},
    }),
})
```

표준 핸들러도 변경해야 한다면 완전히 사용자 지정된 `Client` 구현을 반환하세요. `Client` 타입은 `@mastra/acp`에서 다시 내보냅니다.

## 관련된

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