AcpAgent 클래스

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

대신 상위 Agent가 ACP Agent를 Tool로 호출하도록 하려면 다음을 사용하세요.createACPTool().

사용예

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

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

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

src/mastra/agents/claude-code-agent.ts

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 실행 파일에 전달되는 인수입니다.

env?:

Record<string, string>

ACP 프로세스를 생성할 때 현재 프로세스 환경과 병합할 환경 변수입니다.

cwd?:

string

= process.cwd()

ACP 프로세스 및 ACP 세션의 작업 디렉터리입니다. 기본 로컬 파일 시스템 기준 경로로도 사용됩니다.

session?:

Partial<NewSessionRequest>

ACP 세션 생성 옵션입니다. 기본값은 cwd 또는 process.cwd()와 빈 MCP 서버 목록입니다.

initialize?:

Partial<InitializeRequest>

ACP 초기화 옵션입니다. 기본값은 Mastra 클라이언트 정보, 현재 ACP 프로토콜 버전, 읽기/쓰기 파일 시스템 기능입니다.

authMethodId?:

string

초기화 후 세션 생성 전에 호출할 ACP 인증 방법 ID입니다.

persistSession?:

boolean

= true

각 Prompt 후에도 ACP 프로세스와 세션을 유지할지 여부입니다. 각 Prompt가 완료된 후 프로세스를 중지하려면 false로 설정하세요.

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 생성 결과를 반환합니다.

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 청크로 내보내집니다.

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 목록을 반환합니다.

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

setModel(modelId)

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

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

세션 수명주기

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

src/mastra/agents/code-agent.ts

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를 전달하세요:

src/mastra/agents/code-agent.ts

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를 전달하세요:

src/mastra/agents/code-agent.ts

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 클라이언트 프로토콜 문서
• createACPTool() 참조
• Agent 참조
• 하위 Agent
• Agent 클라이언트 프로토콜 소개
• Agent 클라이언트 프로토콜 스키마