Agent Client Protocol

Mastra supports the Agent Client Protocol (ACP) for running ACP-compatible coding agents from a Mastra agent. Use @mastra/acp to wrap a coding agent process as a Mastra tool or as a subagent.

ACP is useful for coding agents such as Claude Code, Amp, Codex, or any other executable that implements ACP over standard input and output.

When to use ACP

• A Mastra agent should delegate code inspection, editing, or repository tasks to an external coding agent.
• An ACP-compatible agent process should stay alive across calls so it can keep session context.
• A parent agent needs real-time output from a coding agent while the task runs.
• An ACP-compatible agent needs permission prompts before it reads files, writes files, or runs actions.
• File access should go through Mastra's workspace abstraction instead of direct process-only file access.

How ACP works

@mastra/acp starts the configured ACP agent command as a child process and communicates with it using newline-delimited JSON over standard input and output.

The flow is:

1. Configure command, args, and optional connection settings.
2. @mastra/acp spawns the ACP agent process on first use.
3. The client sends ACP initialize and session/new requests.
4. Mastra sends the user task to the ACP agent with session/prompt.
5. The ACP agent streams session updates and message chunks back to Mastra.
6. Mastra returns the buffered output, emits streaming chunks, or handles permission input.
7. The ACP connection stops the process after the prompt when persistSession is false; AcpAgent can keep a reusable process alive across calls by default.

During execution, the ACP client also handles permission requests and file operations. File reads and writes go through Mastra's Workspace, so the ACP agent operates inside the workspace you provide.

Getting started

Install @mastra/acp in a project that already uses @mastra/core. The package requires @mastra/core version 1.34.0 or later.

npm

npm install @mastra/acp

pnpm

pnpm add @mastra/acp

Yarn

yarn add @mastra/acp

Bun

bun add @mastra/acp

@mastra/acp exports two APIs:

• createACPTool(): Create a Mastra tool that sends a task string to an ACP agent and returns an output string.
• AcpAgent: Wrap an ACP agent as a Mastra subagent with generate() and stream() support.

Use ACP as a subagent

Use AcpAgent when a parent Mastra agent should delegate directly to an ACP-compatible coding agent as a subagent.

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

See the AcpAgent reference for all options, methods, and configuration.

Use ACP as a tool

Use createACPTool() when the parent Mastra agent should decide when to call the ACP agent as a tool.

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

See the createACPTool() reference for all options and configuration.

Model selection

ACP agents may expose selectable models. Pass model in the ACP configuration to select a model after session creation, or use AcpAgent.getAvailableModels() and AcpAgent.setModel() to manage models at runtime.

See the AcpAgent model management methods for examples.

Session lifecycle

AcpAgent starts the configured command on first use and creates an ACP session. By default, persistSession is true, so the child process stays alive across calls. Set persistSession: false when each prompt should run in an isolated process.

See the AcpAgent session lifecycle section for details.

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. Pass onPermissionRequest when you need custom permission behavior.

See the createACPTool() permission handling section for a complete example.

Workspace integration

ACP file operations go through Mastra's workspace abstraction. AcpAgent can use a workspace option, and createACPTool() uses the current Mastra workspace from the tool execution context when one is available. Without a workspace, @mastra/acp falls back to a Workspace backed by LocalFilesystem at cwd or process.cwd().

See the AcpAgent workspace integration section for custom workspace examples.

Related

• AcpAgent reference
• createACPTool() reference
• Agent reference
• Subagents
• Agent Client Protocol introduction
• Agent Client Protocol schema