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

# AcpAgent クラス

`AcpAgent` クラスは、Agent Client Protocol（ACP）互換の Coding Agent を Mastra のサブ Agent としてラップします。親 Mastra Agent にリポジトリの調査やコード編集を委譲させる場合に使用します。ACP を利用するその他のタスクをサブ Agent に委譲することもできます。

親 Agent から ACP Agent を Tool として呼び出す場合は、[`createACPTool()`](https://mastra.zisheng.pro/ja/reference/acp/create-acp-tool) を使用します。

## 使用例

ACP 互換の Coding Agent を親 Agent の `agents` マップに登録します。

```typescript
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 モデルを選択します。

```typescript
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`): このサブ Agent に委譲できる場合にモデルへ表示される説明。

**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`): 各プロンプトの終了後も ACP プロセスとセッションを維持するかどうか。各プロンプトの完了後にプロセスを停止するには false に設定します。 (Default: `true`)

**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 セッション作成後、ACP の session/set\_model メソッドを使って選択するモデル ID。

## プロパティ

**id** (`TId`): コンストラクターオプションで指定した読み取り専用のサブ Agent 識別子。

**name** (`string`): このサブ Agent の読み取り専用の表示名。

**description** (`string`): 親 Agent がこのサブ Agent に委譲できる場合に表示される、読み取り専用の説明。

**connection** (`ACPConnection`): Agent プロセスの起動、セッションの作成、プロンプトの送信、更新のストリーミング、モデルの管理に使用する読み取り専用の ACP 接続。

## メソッド

### 生成

#### `generate(messages, options?)`

ACP Agent にプロンプトを送信し、ACP の応答からテキストチャンクをバッファリングして、Mastra サブ Agent の生成結果を返します。

```typescript
const result = await codeAgent.generate('Inspect the repository and summarize the test setup')

console.log(result.text)
```

#### `stream(messages, options?)`

ACP Agent にプロンプトを送信し、Mastra サブ Agent のストリーム結果を返します。ACP の `agent_message_chunk` 更新は、Mastra の `text-delta` チャンクとして送出されます。

```typescript
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()`

必要に応じて ACP プロセスを起動し、ACP セッションが公開するモデルリストを返します。

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

#### `setModel(modelId)`

アクティブな ACP セッションのモデルを選択します。ACP Agent が利用可能なモデルを公開している場合、モデル ID はそのいずれかと一致する必要があります。

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

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

`AcpAgent` は初回使用時に、設定された `command` を起動して ACP クライアントを初期化します。その後、ACP セッションを作成します。デフォルトでは `persistSession` が `true` のため、プロセスとセッションは `generate()`、`stream()`、`getAvailableModels()`、`setModel()` の各呼び出しをまたいで維持されます。

プロンプトごとに新しい ACP プロセスを使用する場合は、`persistSession: false` を設定します。

```typescript
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 との統合

ACP のファイル操作は、Mastra の `Workspace` 抽象化を経由します。`workspace` を渡さない場合、`@mastra/acp` は `LocalFilesystem` を利用する `Workspace` を作成し、`cwd` または `process.cwd()` をファイルシステムのベースパスとして使用します。

ACP Agent が特定のファイルシステム実装を通じて読み書きする必要がある場合は、カスタム `Workspace` を渡します。

```typescript
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` を渡します。

```typescript
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 Client Protocol のドキュメント](https://mastra.zisheng.pro/ja/docs/agents/acp)
- [createACPTool() リファレンス](https://mastra.zisheng.pro/ja/reference/acp/create-acp-tool)
- [Agent リファレンス](https://mastra.zisheng.pro/ja/reference/agents/agent)
- [サブ Agent](https://mastra.zisheng.pro/ja/docs/capabilities/subagents)
- [Agent Client Protocol の概要](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol のスキーマ](https://agentclientprotocol.com/protocol/schema)