AcpAgent class

The AcpAgent class wraps an Agent Client Protocol (ACP)-compatible coding agent as a Mastra subagent. Use it when a parent Mastra agent should delegate repository inspection and code edits. It can also delegate other ACP-backed tasks to the subagent.

If you want the parent agent to call the ACP agent as a tool instead, use createACPTool().

Usage example

Register an ACP-compatible coding agent in a parent agent's agents map:

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

For Claude Code, ACP support is provided by the @agentclientprotocol/claude-agent-acp bridge package. Configure the ACP agent command to run the bridge, then select a Claude model after session creation:

src/mastra/agents/claude-code-agent.ts

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

Constructor parameters

id:

string

Unique identifier for the subagent.

name?:

string

Display name used during agent delegation. Defaults to id.

description:

string

Description shown to the model when it can delegate to this subagent.

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 to keep the ACP process and session alive after each 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. See Extension methods.

workspace?:

Workspace

Workspace used for ACP file read and write requests. Defaults to a Workspace backed by LocalFilesystem at cwd or process.cwd().

model?:

ModelId

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

Properties

id:

TId

Readonly subagent identifier from the constructor options.

name:

string

Readonly display name for this subagent.

description:

string

Readonly description shown when the parent agent can delegate to this subagent.

connection:

ACPConnection

Readonly ACP connection used to start the agent process, create sessions, send prompts, stream updates, and manage models.

Methods

Generation

generate(messages, options?)

Sends the prompt to the ACP agent and buffers text chunks from the response before returning a Mastra subagent generate result.

const result = await codeAgent.generate('Inspect the repository and summarize the test setup')

console.log(result.text)

stream(messages, options?)

Sends the prompt to the ACP agent and returns a Mastra subagent stream result. ACP agent_message_chunk updates are emitted as Mastra text-delta chunks.

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() and resumeStream() aren't supported and throw an error when called.

Model management

getAvailableModels()

Starts the ACP process if needed and returns the model list advertised by the ACP session.

const models = await codeAgent.getAvailableModels()
// [{ modelId: 'claude-sonnet-4-6', name: 'Claude Sonnet' }, ...]

setModel(modelId)

Selects a model for the active ACP session. If the ACP agent advertises available models, the model ID must match one of them.

await codeAgent.setModel('claude-sonnet-4-6')

Session lifecycle

AcpAgent starts the configured command on first use and initializes the ACP client. It then creates an ACP session. By default, persistSession is true, so the process and session stay alive across generate(), stream(), getAvailableModels(), and setModel() calls.

Set persistSession: false when each prompt should run in a fresh ACP process:

src/mastra/agents/code-agent.ts

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

With persistSession: false, @mastra/acp stops the ACP process after each prompt completes.

Workspace integration

ACP file operations go through Mastra's Workspace abstraction. If you don't pass workspace, @mastra/acp creates a Workspace backed by LocalFilesystem and uses cwd or process.cwd() as the filesystem base path.

Pass a custom Workspace when the ACP agent should read and write through a specific filesystem implementation:

src/mastra/agents/code-agent.ts

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

Use cwd and workspace together when the ACP process should start in one directory but file operations should use an explicitly configured workspace root.

Permission handling

ACP agents may ask the client to choose a permission option before they continue. By default, AcpAgent 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 { 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,
      },
    }
  },
})

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

Related

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