createACPTool()

The createACPTool() function creates a Mastra tool that sends a task string to an Agent Client Protocol (ACP)-compatible coding agent and returns the final ACP response as output. Use it when a parent agent should decide when to call the ACP agent as a tool.

If you want to register the ACP agent as a Mastra subagent instead, use the AcpAgent class.

Usage example

Create a code editing tool and register it on a parent agent:

src/mastra/agents/code-supervisor.ts

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.5',
  tools: {
    codeAgentTool,
  },
})

Parameters

id:

string

Unique identifier for the Mastra tool.

description:

string

Description shown to the model when it can call this tool.

command:

string

ACP agent executable to spawn.

args?:

string[]

= []

Arguments passed to the ACP agent executable.

env?:

Record<string, string>

Environment variables to merge with the current process environment when spawning the ACP process.

cwd?:

string

= process.cwd()

Working directory for the ACP process and ACP session. Also used as the default local filesystem base path.

session?:

Partial<NewSessionRequest>

ACP session creation options. Defaults to `cwd` or `process.cwd()` and an empty MCP server list.

initialize?:

Partial<InitializeRequest>

ACP initialization options. Defaults to Mastra client information, the current ACP protocol version, and read/write filesystem capabilities.

authMethodId?:

string

ACP authentication method ID to invoke after initialization and before session creation.

persistSession?:

boolean

= true

Whether the ACP connection created for a tool execution disconnects after the prompt. Set to `false` to stop the process after each prompt completes.

onPermissionRequest?:

(request: RequestPermissionRequest) => Promise<RequestPermissionResponse>

Callback invoked when the ACP agent requests permission. Defaults to selecting the first permission option, or cancelling when no option is available.

workspace?:

Workspace

Workspace option from the shared ACP connection options. During tool execution, `createACPTool()` passes the current Mastra workspace from the execution context when one is available; otherwise the ACP connection falls back to a local filesystem workspace. Use `AcpAgent` when you need to provide an explicit workspace instance.

model?:

ModelId

Model ID to select after ACP session creation using the ACP `session/set_model` method.

Input schema

task:

string

The task to send to the ACP agent.

Output schema

output:

string

The final text output returned by the ACP agent.

Suspend and resume schema

createACPTool() defines suspend and resume schemas for permission request payloads. Permission decisions are returned through onPermissionRequest; by default, @mastra/acp selects the first option returned by the ACP agent, or cancels when no option is available.

Suspend payload

permissionRequest:

{ title: string; options: { optionId: string; name: string }[] }

Permission request title and selectable options returned by the ACP agent.

Resume payload

optionId?:

string

Permission option ID to select when resuming with `outcome: "selected"`.

outcome?:

"selected" | "cancelled"

Permission decision used to continue or cancel the ACP request.

Session lifecycle

Each tool execution creates an ACP connection, starts the configured command, initializes the ACP client, creates an ACP session, and sends the task with ACP session/prompt.

By default, persistSession is true for the ACP connection created during tool execution. Set persistSession: false when the ACP process should stop as soon as that prompt completes.

Use AcpAgent when you need a reusable ACP subagent instance with explicit session lifecycle control across calls.

Permission handling

ACP agents may ask the client to choose a permission option before they continue. By default, @mastra/acp selects the first option returned by the ACP agent, or cancels when no option is available.

Pass onPermissionRequest to inspect the request and return your own permission response:

src/mastra/agents/code-agent.ts

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

Use this callback to enforce local policy, inspect the permission title, or route the decision to your own approval flow.

Related

• Agent Client Protocol docs
• AcpAgent class reference
• Tool reference
• Agent Client Protocol introduction
• Agent Client Protocol schema