createACPTool()
createACPTool() 関数は、task 文字列を Agent Client Protocol（ACP）互換の Coding Agent に送信し、最終的な ACP の応答を output として返す Mastra Tool を作成します。ACP Agent を Tool としていつ呼び出すかを親 Agent に判断させる場合に使用します。
ACP Agent を Mastra のサブ Agent として登録する場合は、AcpAgent クラスを使用します。
使用例使用例への直接リンク
コード編集 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() はそれを渡します。なければ、ACP 接続はローカルファイルシステムの Workspace にフォールバックします。明示的な Workspace インスタンスを指定する必要がある場合は AcpAgent を使用します。model?:
session/set_model メソッドを使って選択するモデル ID。入力スキーマ入力スキーマへの直接リンク
task:
出力スキーマ出力スキーマへの直接リンク
output:
一時停止と再開のスキーマ一時停止と再開のスキーマへの直接リンク
createACPTool() は、権限リクエストのペイロードに対する一時停止と再開のスキーマを定義します。権限に関する判断は onPermissionRequest を通じて返されます。デフォルトでは、@mastra/acp は ACP Agent が返した最初のオプションを選択し、利用可能なオプションがない場合はキャンセルします。
一時停止ペイロード一時停止ペイロードへの直接リンク
permissionRequest:
再開ペイロード再開ペイロードへの直接リンク
optionId?:
outcome: "selected" で再開するときに選択する権限オプションの ID。outcome?:
セッションのライフサイクルセッションのライフサイクルへの直接リンク
Tool を実行するたびに ACP 接続が作成され、設定された command が起動します。ACP クライアントを初期化して ACP セッションを作成してから、ACP の session/prompt で task を送信します。
デフォルトでは、Tool の実行中に作成される ACP 接続の persistSession は true です。そのプロンプトが完了した直後に 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 リクエストセットに含まれないカスタム拡張メソッドをクライアント上で呼び出します。デフォルトのクライアントは、不明なメソッドを「Method not found」エラーで拒否するため、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 から再エクスポートされています。