AcpAgent クラス
AcpAgent クラスは、Agent Client Protocol（ACP）互換の Coding Agent を Mastra のサブ Agent としてラップします。親 Mastra Agent にリポジトリの調査やコード編集を委譲させる場合に使用します。ACP を利用するその他のタスクをサブ Agent に委譲することもできます。
親 Agent から ACP Agent を Tool として呼び出す場合は、createACPTool() を使用します。
使用例使用例への直接リンク
ACP 互換の Coding Agent を親 Agent の agents マップに登録します。
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 モデルを選択します。
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:
name?:
id です。description:
command:
args?:
env?:
cwd?:
session?:
cwd または process.cwd() と、空の MCP サーバーリストです。initialize?:
authMethodId?:
persistSession?:
false に設定します。onPermissionRequest?:
createClient?:
extMethod や extNotification のハンドラーなどでラップまたは拡張できます。拡張メソッドを参照してください。workspace?:
cwd または process.cwd() を基点とする LocalFilesystem を利用した Workspace です。model?:
session/set_model メソッドを使って選択するモデル ID。プロパティプロパティへの直接リンク
id:
name:
description:
connection:
メソッドメソッドへの直接リンク
生成生成への直接リンク
generate(messages, options?)generatemessages-optionsへの直接リンク
ACP Agent にプロンプトを送信し、ACP の応答からテキストチャンクをバッファリングして、Mastra サブ Agent の生成結果を返します。
const result = await codeAgent.generate('Inspect the repository and summarize the test setup')
console.log(result.text)
stream(messages, options?)streammessages-optionsへの直接リンク
ACP Agent にプロンプトを送信し、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() はサポートされておらず、呼び出すとエラーをスローします。
モデル管理モデル管理への直接リンク
getAvailableModels()getavailablemodelsへの直接リンク
必要に応じて ACP プロセスを起動し、ACP セッションが公開するモデルリストを返します。
const models = await codeAgent.getAvailableModels()
// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]
setModel(modelId)setmodelmodelidへの直接リンク
アクティブな ACP セッションのモデルを選択します。ACP Agent が利用可能なモデルを公開している場合、モデル ID はそのいずれかと一致する必要があります。
await codeAgent.setModel('claude-sonnet-4-6')
セッションのライフサイクルセッションのライフサイクルへの直接リンク
AcpAgent は初回使用時に、設定された command を起動して ACP クライアントを初期化します。その後、ACP セッションを作成します。デフォルトでは persistSession が true のため、プロセスとセッションは generate()、stream()、getAvailableModels()、setModel() の各呼び出しをまたいで維持されます。
プロンプトごとに新しい ACP プロセスを使用する場合は、persistSession: false を設定します。
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 の場合、@mastra/acp は各プロンプトの完了後に ACP プロセスを停止します。
Workspace との統合Workspace との統合への直接リンク
ACP のファイル操作は、Mastra の Workspace 抽象化を経由します。workspace を渡さない場合、@mastra/acp は LocalFilesystem を利用する Workspace を作成し、cwd または process.cwd() をファイルシステムのベースパスとして使用します。
ACP Agent が特定のファイルシステム実装を通じて読み書きする必要がある場合は、カスタム Workspace を渡します。
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 を渡します。
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,
},
}
},
})
このコールバックを使用すると、ローカルポリシーを適用したり、権限のタイトルを確認したりできます。独自の承認フローへ判断を委ねることもできます。