Agent Client Protocol

Mastra は、Mastra Agent から ACP 互換のコーディング Agent を実行するための Agent Client Protocol (ACP) をサポートしています。@mastra/acp を使用すると、コーディング Agent のプロセスを Mastra Tool またはサブ Agent としてラップできます。

ACP は、Claude Code、Amp、Codex など、標準入出力上で ACP を実装する実行可能なコーディング Agent に適しています。

ACP を使用する場面

• Mastra Agent から外部のコーディング Agent に、コードの調査や編集、リポジトリのタスクを委任する場合。
• セッションコンテキストを維持するため、ACP 互換 Agent のプロセスを呼び出し間で存続させる場合。
• タスクの実行中に、親 Agent がコーディング Agent の出力をリアルタイムで必要とする場合。
• ACP 互換 Agent がファイルの読み書きやアクションの実行前に権限を要求する必要がある場合。
• プロセスから直接ファイルにアクセスせず、Mastra の Workspace 抽象化を経由させる場合。

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 の場合、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 は2つの API をエクスポートします。

• createACPTool(): task 文字列を ACP Agent に送信し、output 文字列を返す Mastra Tool を作成します。
• AcpAgent: ACP Agent を、generate() と stream() をサポートする 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() リファレンスを参照してください。

モデルの選択

ACP Agent は選択可能なモデルを公開することがあります。セッション作成後にモデルを選択するには ACP 設定で model を渡します。実行時にモデルを管理するには、AcpAgent.getAvailableModels() と AcpAgent.setModel() を使用します。

例については、AcpAgent のモデル管理メソッドを参照してください。

セッションのライフサイクル

AcpAgent は初回使用時に設定済みのコマンドを起動し、ACP セッションを作成します。デフォルトでは persistSession が true のため、子プロセスは呼び出し間で存続します。各プロンプトを分離したプロセスで実行する場合は、persistSession: false を設定します。

詳細は、AcpAgent のセッションライフサイクルを参照してください。

権限の処理

ACP Agent は処理を続行する前に、権限オプションの選択をクライアントに求めることがあります。デフォルトでは、@mastra/acp は ACP Agent が返した最初のオプションを選択します。権限の動作をカスタマイズする場合は、onPermissionRequest を渡します。

完全な例は、createACPTool() の権限処理を参照してください。

Workspace との統合

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 Client Protocol の概要
• Agent Client Protocol のスキーマ