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.6-sol',
  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.

createClient?:

(defaultClient: Client) => Client

Customize the ACP client used to answer agent requests. Receives the default client so it can be wrapped or extended, for example with extMethod and extNotification handlers.

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 and starts the configured command. It initializes the ACP client and creates an ACP session before sending 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 or inspect the permission title. It can also route the decision to your own approval flow.

Extension methods

Some ACP agents call custom extension methods on the client, outside the standard ACP request set. The default client rejects unknown methods with a "Method not found" error, which can abort the agent's turn.

Pass createClient to extend or replace the default client. The callback receives the default client and returns the client used for the connection:

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'],
  createClient: defaultClient =>
    Object.assign(defaultClient, {
      async extMethod(method: string, params: Record<string, unknown>) {
        return {}
      },
      async extNotification(method: string, params: Record<string, unknown>) {},
    }),
})

Return a fully custom Client implementation when you need to change the standard handlers as well. The Client type is re-exported from @mastra/acp.

Related

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