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

# AcpAgent 類別

`AcpAgent` 類別會將 Agent Client Protocol（ACP）相容的 Coding Agent 包裝為 Mastra subagent。當上層 Mastra Agent 應委派 repository 檢查與程式碼編輯工作時，可使用此類別。它也可以將其他由 ACP 支援的工作委派給 subagent。

若要改由上層 Agent 將 ACP Agent 當作 Tool 呼叫，請使用 [`createACPTool()`](https://mastra.zisheng.pro/zh-TW/reference/acp/create-acp-tool)。

## 使用範例

在上層 Agent 的 `agents` map 中註冊 ACP 相容的 Coding Agent：

```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` bridge 套件提供。請將 ACP Agent 指令設為執行此 bridge，然後在建立 session 後選取 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`): subagent 的唯一識別碼。

**name** (`string`): 委派 Agent 工作時使用的顯示名稱。預設為 id。

**description** (`string`): 模型可將工作委派給此 subagent 時顯示的說明。

**command** (`string`): 要產生的 ACP Agent 可執行檔。

**args** (`string[]`): 傳給 ACP Agent 可執行檔的引數。 (Default: `[]`)

**env** (`Record<string, string>`): 產生 ACP 處理程序時，要與目前處理程序環境合併的環境變數。

**cwd** (`string`): ACP 處理程序與 ACP session 的工作目錄，也會作為預設的本機檔案系統基底路徑。 (Default: `process.cwd()`)

**session** (`Partial<NewSessionRequest>`): ACP session 建立選項。預設使用 cwd 或 process.cwd()，並使用空的 MCP 伺服器清單。

**initialize** (`Partial<InitializeRequest>`): ACP 初始化選項。預設使用 Mastra 使用者端資訊、目前 ACP 通訊協定版本，以及檔案系統讀寫功能。

**authMethodId** (`string`): 初始化後、建立 session 前要叫用的 ACP 驗證方法 ID。

**persistSession** (`boolean`): 每個 prompt 完成後是否讓 ACP 處理程序與 session 繼續執行。設為 false 可在每個 prompt 完成後停止處理程序。 (Default: `true`)

**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): ACP Agent 要求權限時叫用的 callback。預設會選取第一個權限選項；沒有可用選項時則取消。

**createClient** (`(defaultClient: Client) => Client`): 自訂用來回應 Agent 要求的 ACP 使用者端。此函式會接收預設使用者端，以便加以包裝或擴充，例如加入 extMethod 與 extNotification handler。請參閱擴充方法。

**workspace** (`Workspace`): 用於 ACP 檔案讀寫要求的 Workspace。預設為由 cwd 或 process.cwd() 路徑上的 LocalFilesystem 支援的 Workspace。

**model** (`ModelId`): 建立 ACP session 後，使用 ACP session/set\_model 方法選取的模型 ID。

## 屬性

**id** (`TId`): 建構函式選項中唯讀的 subagent 識別碼。

**name** (`string`): 此 subagent 的唯讀顯示名稱。

**description** (`string`): 上層 Agent 可委派工作給此 subagent 時顯示的唯讀說明。

**connection** (`ACPConnection`): 唯讀 ACP connection，用於啟動 Agent 處理程序、建立 session、傳送 prompt、串流更新及管理模型。

## 方法

### 生成

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

將 prompt 傳送給 ACP Agent、緩衝 ACP 回應中的文字 chunk，並傳回 Mastra subagent generate 結果。

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

console.log(result.text)
```

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

將 prompt 傳送給 ACP Agent，並傳回 Mastra subagent stream 結果。ACP `agent_message_chunk` 更新會以 Mastra `text-delta` chunk 發出。

```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 session 公告的模型清單。

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

#### `setModel(modelId)`

為作用中的 ACP session 選取模型。如果 ACP Agent 有公告可用模型，模型 ID 必須符合其中一個模型。

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

## Session 生命週期

`AcpAgent` 會在首次使用時啟動設定的 `command` 並初始化 ACP 使用者端，接著建立 ACP session。`persistSession` 預設為 `true`，因此在呼叫 `generate()`、`stream()`、`getAvailableModels()` 與 `setModel()` 之間，處理程序與 session 都會繼續執行。

若每個 prompt 都應在新的 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` 會在每個 prompt 完成時停止 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,
      },
    }
  },
})
```

可使用此 callback 強制執行本機 policy，或檢查權限標題，也可以將決策導向自己的核准流程。

## 相關內容

- [Agent Client Protocol 文件](https://mastra.zisheng.pro/zh-TW/docs/agents/acp)
- [createACPTool() 參考文件](https://mastra.zisheng.pro/zh-TW/reference/acp/create-acp-tool)
- [Agent 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agents/agent)
- [Subagent](https://mastra.zisheng.pro/zh-TW/docs/capabilities/subagents)
- [Agent Client Protocol 簡介](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)