> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# createACPTool()

`createACPTool()` 関数は、`task` 文字列を Agent Client Protocol（ACP）互換の Coding Agent に送信し、最終的な ACP の応答を `output` として返す Mastra Tool を作成します。ACP Agent を Tool としていつ呼び出すかを親 Agent に判断させる場合に使用します。

ACP Agent を Mastra のサブ Agent として登録する場合は、[`AcpAgent` クラス](https://mastra.zisheng.pro/ja/reference/acp/acp-agent)を使用します。

## 使用例

コード編集 Tool を作成し、親 Agent に登録します。

```typescript
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** (`string`): Mastra Tool の一意の識別子。

**description** (`string`): この Tool を呼び出せる場合にモデルへ表示される説明。

**command** (`string`): 起動する ACP Agent の実行ファイル。

**args** (`string[]`): ACP Agent の実行ファイルに渡す引数。 (Default: `[]`)

**env** (`Record<string, string>`): ACP プロセスの起動時に、現在のプロセス環境へマージする環境変数。

**cwd** (`string`): ACP プロセスと ACP セッションの作業ディレクトリ。デフォルトのローカルファイルシステムのベースパスとしても使用されます。 (Default: `process.cwd()`)

**session** (`Partial<NewSessionRequest>`): ACP セッションの作成オプション。デフォルトは cwd または process.cwd() と、空の MCP サーバーリストです。

**initialize** (`Partial<InitializeRequest>`): ACP の初期化オプション。デフォルトは Mastra クライアント情報、現在の ACP プロトコルバージョン、読み書き可能なファイルシステム機能です。

**authMethodId** (`string`): 初期化後、セッション作成前に呼び出す ACP 認証方式の ID。

**persistSession** (`boolean`): Tool 実行用に作成した ACP 接続を、プロンプトの終了後に切断するかどうか。各プロンプトの完了後にプロセスを停止するには false に設定します。 (Default: `true`)

**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): ACP Agent が権限を要求したときに呼び出されるコールバック。デフォルトでは最初の権限オプションを選択し、利用可能なオプションがない場合はキャンセルします。

**createClient** (`(defaultClient: Client) => Client`): Agent のリクエストに応答する ACP クライアントをカスタマイズします。デフォルトのクライアントを受け取るため、extMethod や extNotification のハンドラーなどでラップまたは拡張できます。

**workspace** (`Workspace`): 共有 ACP 接続オプションの Workspace オプション。Tool の実行時、現在の Mastra Workspace が実行コンテキストにあれば、createACPTool() はそれを渡します。なければ、ACP 接続はローカルファイルシステムの Workspace にフォールバックします。明示的な Workspace インスタンスを指定する必要がある場合は AcpAgent を使用します。

**model** (`ModelId`): ACP セッション作成後、ACP の session/set\_model メソッドを使って選択するモデル ID。

## 入力スキーマ

**task** (`string`): ACP Agent に送信するタスク。

## 出力スキーマ

**output** (`string`): ACP Agent が返す最終的なテキスト出力。

## 一時停止と再開のスキーマ

`createACPTool()` は、権限リクエストのペイロードに対する一時停止と再開のスキーマを定義します。権限に関する判断は `onPermissionRequest` を通じて返されます。デフォルトでは、`@mastra/acp` は ACP Agent が返した最初のオプションを選択し、利用可能なオプションがない場合はキャンセルします。

### 一時停止ペイロード

**permissionRequest** (`{ title: string; options: { optionId: string; name: string }[] }`): ACP Agent が返す権限リクエストのタイトルと選択可能なオプション。

### 再開ペイロード

**optionId** (`string`): outcome: "selected" で再開するときに選択する権限オプションの ID。

**outcome** (`"selected" | "cancelled"`): ACP リクエストを続行またはキャンセルするための権限に関する判断。

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

Tool を実行するたびに ACP 接続が作成され、設定された `command` が起動します。ACP クライアントを初期化して ACP セッションを作成してから、ACP の `session/prompt` で `task` を送信します。

デフォルトでは、Tool の実行中に作成される ACP 接続の `persistSession` は `true` です。そのプロンプトが完了した直後に ACP プロセスを停止する場合は、`persistSession: false` を設定します。

呼び出しをまたいでセッションのライフサイクルを明示的に制御できる、再利用可能な ACP サブ Agent インスタンスが必要な場合は、[`AcpAgent`](https://mastra.zisheng.pro/ja/reference/acp/acp-agent) を使用します。

## 権限の処理

ACP Agent は処理を続行する前に、権限オプションの選択をクライアントに求める場合があります。デフォルトでは、`@mastra/acp` は ACP Agent が返した最初のオプションを選択し、利用可能なオプションがない場合はキャンセルします。

リクエストを確認して独自の権限応答を返すには、`onPermissionRequest` を渡します。

```typescript
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` を渡します。このコールバックはデフォルトのクライアントを受け取り、接続に使用するクライアントを返します。

```typescript
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` から再エクスポートされています。

## 関連項目

- [Agent Client Protocol のドキュメント](https://mastra.zisheng.pro/ja/docs/agents/acp)
- [AcpAgent クラスのリファレンス](https://mastra.zisheng.pro/ja/reference/acp/acp-agent)
- [Tool リファレンス](https://mastra.zisheng.pro/ja/reference/tools/create-tool)
- [Agent Client Protocol の概要](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol のスキーマ](https://agentclientprotocol.com/protocol/schema)