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

# AcpAgent 类

`AcpAgent` 类将兼容 Agent Client Protocol（ACP）的编码 Agent 封装为 Mastra 子 Agent。当父级 Mastra Agent 需要委派代码仓库检查和代码编辑任务时，可以使用此类。它也可以将其他由 ACP 支持的任务委派给子 Agent。

如果希望父级 Agent 改为将 ACP Agent 作为 Tool 调用，请使用 [`createACPTool()`](https://mastra.zisheng.pro/reference/acp/create-acp-tool)。

## 使用示例

在父级 Agent 的 `agents` 映射中注册兼容 ACP 的编码 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` 桥接包提供。将 ACP Agent 命令配置为运行该桥接程序，然后在创建 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`): 子 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 Session 的工作目录。也用作默认的本地文件系统基础路径。 (Default: `process.cwd()`)

**session** (`Partial<NewSessionRequest>`): ACP Session 创建选项。默认使用 cwd 或 process.cwd()，MCP server 列表默认为空。

**initialize** (`Partial<InitializeRequest>`): ACP 初始化选项。默认使用 Mastra Client 信息、当前 ACP 协议版本以及文件系统读写能力。

**authMethodId** (`string`): 初始化之后、创建 Session 之前要调用的 ACP 身份验证方法 ID。

**persistSession** (`boolean`): 是否在每次提示词处理后保持 ACP 进程和 Session 运行。设为 false 可在每次提示词处理完成后停止进程。 (Default: `true`)

**onPermissionRequest** (`(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>`): ACP Agent 请求权限时调用的回调。默认选择第一个权限选项；没有可用选项时则取消。

**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`): 构造函数选项中的只读子 Agent 标识符。

**name** (`string`): 此子 Agent 的只读显示名称。

**description** (`string`): 父级 Agent 可以委派给此子 Agent 时显示的只读描述。

**connection** (`ACPConnection`): 只读 ACP connection，用于启动 Agent 进程、创建 Session、发送提示词、流式传输更新和管理模型。

## 方法

### 生成

#### `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 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 Client。然后它会创建 ACP Session。默认情况下，`persistSession` 为 `true`，因此在调用 `generate()`、`stream()`、`getAvailableModels()` 和 `setModel()` 期间，进程和 Session 会保持运行。

如果每个提示词都应在新的 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 可能会要求 Client 选择一个权限选项，然后才能继续。默认情况下，`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/docs/agents/acp)
- [createACPTool() 参考](https://mastra.zisheng.pro/reference/acp/create-acp-tool)
- [Agent 参考](https://mastra.zisheng.pro/reference/agents/agent)
- [子 Agent](https://mastra.zisheng.pro/docs/capabilities/subagents)
- [Agent Client Protocol 简介](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)