AcpAgent 類別

AcpAgent 類別會將兼容 Agent Client Protocol (ACP) 的編程助手包裝成 Mastra subagent。當父 Mastra Agent 應把儲存庫檢查和程式碼編輯工作委派出去時，可使用此類別。它亦可把其他由 ACP 支援的工作委派給 subagent。

如希望父 Agent 改為以 Tool 形式呼叫 ACP Agent，請使用 createACPTool()。

使用範例

在父 Agent 的 agents map 中註冊兼容 ACP 的編程助手：

src/mastra/agents/code-supervisor.ts

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 指令以執行橋接套件，然後在建立 session 後選擇 Claude 模型：

src/mastra/agents/claude-code-agent.ts

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 可執行檔的引數。

env?:

Record<string, string>

啟動 ACP 程序時，要與目前程序環境合併的環境變數。

cwd?:

string

= process.cwd()

ACP 程序及 ACP session 的工作目錄，亦用作預設的本機檔案系統基礎路徑。

session?:

Partial<NewSessionRequest>

ACP session 建立選項。預設使用 cwd 或 process.cwd()，並採用空的 MCP 伺服器清單。

initialize?:

Partial<InitializeRequest>

ACP 初始化選項。預設使用 Mastra client 資訊、目前的 ACP protocol 版本，以及檔案系統讀寫功能。

authMethodId?:

string

在初始化後、建立 session 前呼叫的 ACP 驗證方法 ID。

persistSession?:

boolean

= true

每個 prompt 完成後，是否讓 ACP 程序及 session 繼續運行。設為 false 可在每個 prompt 完成後停止程序。

onPermissionRequest?:

(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>

ACP Agent 要求權限時呼叫的 callback。預設選擇第一個權限選項；如沒有可用選項，則取消要求。

createClient?:

(defaultClient: Client) => Client

自訂用於回應 Agent 要求的 ACP client。函數會接收預設 client，讓你包裝或擴充它，例如加入 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 回應中的文字區塊，並傳回 Mastra subagent generate 結果。

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 區塊輸出。

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 公布的模型清單。

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

setModel(modelId)

為使用中的 ACP session 選擇模型。如 ACP Agent 公布了可用模型，模型 ID 必須與其中一個相符。

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

Session 生命週期

AcpAgent 會在首次使用時啟動已設定的 command，並初始化 ACP client，然後建立 ACP session。persistSession 預設為 true，所以在呼叫 generate()、stream()、getAvailableModels() 和 setModel() 之間，程序及 session 會繼續運行。

如每個 prompt 都應在新的 ACP 程序中運行，請設定 persistSession: false：

src/mastra/agents/code-agent.ts

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：

src/mastra/agents/code-agent.ts

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 在繼續操作前，可能會要求 client 選擇權限選項。AcpAgent 預設會選擇 ACP Agent 傳回的第一個選項；如沒有可用選項，則取消要求。

傳入 onPermissionRequest 可檢查要求，並傳回自己的權限回應：

src/mastra/agents/code-agent.ts

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 可強制執行本機政策或檢查權限要求的標題，亦可把決定轉交至你自己的核准流程。

相關內容

• Agent Client Protocol 文檔
• createACPTool() 參考
• Agent 參考
• Subagent
• Agent Client Protocol 簡介
• Agent Client Protocol schema