생성ACPTool()
그만큼createACPTool()함수는 다음을 보내는 Mastra Tool을 생성합니다.task문자열을 ACP(Agent 클라이언트 프로토콜) 호환 코딩 Agent에 전송하고 최종 ACP 응답을 다음과 같이 반환합니다.output. 상위 Agent가 ACP Agent를 Tool로 호출할 시기를 결정해야 할 때 사용하십시오.
대신 ACP Agent를 Mastra 하위 Agent로 등록하려면AcpAgent class.
사용예사용예에 대한 직접 링크
코드 편집 Tool을 만들고 상위 Agent에 등록합니다.
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:
description:
command:
args?:
env?:
cwd?:
session?:
cwd 또는 process.cwd()와 빈 MCP 서버 목록입니다.initialize?:
authMethodId?:
persistSession?:
false로 설정하세요.onPermissionRequest?:
createClient?:
extMethod 및 extNotification 핸들러를 추가할 수 있습니다.workspace?:
createACPTool()은 실행 컨텍스트의 현재 Mastra Workspace를 전달합니다. 그렇지 않으면 ACP 연결은 로컬 파일 시스템 Workspace를 대신 사용합니다. 명시적인 Workspace 인스턴스를 제공해야 한다면 AcpAgent를 사용하세요.model?:
session/set_model 메서드를 사용하여 ACP 세션 생성 후 선택할 Model ID입니다.입력 스키마입력 스키마에 대한 직접 링크
task:
출력 스키마출력 스키마에 대한 직접 링크
output:
일시중단 및 재개 스키마일시중단 및 재개 스키마에 대한 직접 링크
createACPTool()은 권한 요청 페이로드의 일시 중지 및 재개 스키마를 정의합니다. 권한 결정은 onPermissionRequest를 통해 반환됩니다. 기본적으로 @mastra/acp는 ACP Agent가 반환한 첫 번째 옵션을 선택하며, 사용 가능한 옵션이 없으면 취소합니다.
페이로드 일시중단페이로드 일시중단에 대한 직접 링크
permissionRequest:
페이로드 재개페이로드 재개에 대한 직접 링크
optionId?:
outcome: "selected"로 재개할 때 선택할 권한 옵션 ID입니다.outcome?:
세션 수명주기세션 수명주기에 대한 직접 링크
각 Tool 실행은 ACP 연결을 생성하고 구성된 command를 시작합니다. task를 ACP session/prompt로 보내기 전에 ACP 클라이언트를 초기화하고 ACP 세션을 생성합니다.
기본적으로 Tool 실행 중 생성되는 ACP 연결의 persistSession은 true입니다. 해당 Prompt가 완료되는 즉시 ACP 프로세스를 중지해야 한다면 persistSession: false를 설정하세요.
여러 호출에서 명시적으로 세션 수명 주기를 제어할 수 있는 재사용 가능한 ACP 하위 Agent 인스턴스가 필요하다면 AcpAgent를 사용하세요.
권한 처리권한 처리에 대한 직접 링크
ACP Agent는 계속 진행하기 전에 클라이언트에 권한 옵션을 선택하도록 요청할 수 있습니다. 기본적으로 @mastra/acp는 ACP Agent가 반환한 첫 번째 옵션을 선택하며, 사용 가능한 옵션이 없으면 취소합니다.
요청을 검사하고 자체 권한 응답을 반환하려면 onPermissionRequest를 전달하세요:
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를 전달하세요. 콜백은 기본 클라이언트를 전달받아 연결에 사용할 클라이언트를 반환합니다:
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에서 다시 내보냅니다.