Agent 클라이언트 프로토콜

마스트라는 다음을 지원합니다.Agent Client Protocol (ACP)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

npm install @mastra/acp

pnpm

pnpm add @mastra/acp

Yarn

yarn add @mastra/acp

Bun

bun add @mastra/acp

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

• createACPTool(): ACP Agent에 task 문자열을 보내고 output 문자열을 반환하는 Mastra Tool을 만듭니다.
• AcpAgent: generate() 및 stream()을 지원하도록 ACP Agent를 Mastra 하위 Agent로 래핑합니다.

ACP를 하위 Agent로 사용

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

src/mastra/agents/code-supervisor.ts

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 참조를 확인하세요.

ACP를 Tool로 사용

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

src/mastra/agents/code-supervisor.ts

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() 참조를 확인하세요.

Model 선택

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

세션 수명주기

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

권한 처리

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

작업공간 통합

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

관련된

• AcpAgent 참조
• createACPTool() 참조
• Agent 참조
• 하위 Agent
• Agent 클라이언트 프로토콜 소개
• Agent 클라이언트 프로토콜 스키마