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

# createACPTool()

`createACPTool()` 函数会创建一个 Mastra Tool，将 `task` 字符串发送给兼容 Agent Client Protocol（ACP）的编码 Agent，并将最终 ACP 响应作为 `output` 返回。当父级 Agent 应自行决定何时将 ACP Agent 作为 Tool 调用时，可以使用此函数。

如果希望改为将 ACP Agent 注册为 Mastra 子 Agent，请使用 [`AcpAgent` 类](https://mastra.zisheng.pro/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 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`): 为执行 Tool 而创建的 ACP connection 是否在提示词处理后断开连接。设为 false 可在每次提示词处理完成后停止进程。 (Default: `true`)

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

**createClient** (`(defaultClient: Client) => Client`): 自定义用于响应 Agent 请求的 ACP Client。它接收默认 Client，以便对其进行封装或扩展，例如添加 extMethod 和 extNotification handler。

**workspace** (`Workspace`): 共享 ACP connection 选项中的 Workspace 选项。执行 Tool 时，如果执行上下文中存在当前 Mastra Workspace，createACPTool() 会将其传入；否则 ACP connection 会回退到本地文件系统 Workspace。如果需要提供显式 Workspace 实例，请使用 AcpAgent。

**model** (`ModelId`): 创建 ACP Session 后，使用 ACP session/set\_model 方法选择的模型 ID。

## 输入 schema

**task** (`string`): 要发送给 ACP Agent 的任务。

## 输出 schema

**output** (`string`): ACP Agent 返回的最终文本输出。

## 暂停和恢复 schema

`createACPTool()` 为权限请求 payload 定义了暂停和恢复 schema。权限决策通过 `onPermissionRequest` 返回；默认情况下，`@mastra/acp` 会选择 ACP Agent 返回的第一个选项，如果没有可用选项则取消。

### 暂停 payload

**permissionRequest** (`{ title: string; options: { optionId: string; name: string }[] }`): ACP Agent 返回的权限请求标题和可选选项。

### 恢复 payload

**optionId** (`string`): 使用 outcome: "selected" 恢复时要选择的权限选项 ID。

**outcome** (`"selected" | "cancelled"`): 用于继续或取消 ACP 请求的权限决策。

## Session 生命周期

每次执行 Tool 都会创建 ACP connection 并启动已配置的 `command`。它会初始化 ACP Client 并创建 ACP Session，然后使用 ACP `session/prompt` 发送 `task`。

默认情况下，执行 Tool 期间创建的 ACP connection 将 `persistSession` 设为 `true`。如果 ACP 进程应在该提示词处理完成后立即停止，请设置 `persistSession: false`。

如果需要一个可跨调用复用并可显式控制 Session 生命周期的 ACP 子 Agent 实例，请使用 [`AcpAgent`](https://mastra.zisheng.pro/reference/acp/acp-agent)。

## 权限处理

ACP Agent 可能会要求 Client 选择一个权限选项，然后才能继续。默认情况下，`@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 请求集之外，调用 Client 上的自定义扩展方法。默认 Client 会拒绝未知方法并返回 “Method not found” 错误，这可能会中止 Agent 的当前轮次。

传入 `createClient` 可扩展或替换默认 Client。此回调接收默认 Client，并返回用于 connection 的 Client：

```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>) {},
    }),
})
```

如果还需要更改标准 handler，请返回完全自定义的 `Client` 实现。`Client` 类型从 `@mastra/acp` 重新导出。

## 相关内容

- [Agent Client Protocol 文档](https://mastra.zisheng.pro/docs/agents/acp)
- [AcpAgent 类参考](https://mastra.zisheng.pro/reference/acp/acp-agent)
- [Tool 参考](https://mastra.zisheng.pro/reference/tools/create-tool)
- [Agent Client Protocol 简介](https://agentclientprotocol.com/overview/introduction)
- [Agent Client Protocol schema](https://agentclientprotocol.com/protocol/schema)