Agent Client Protocol (ACP) Guide

TL;DR

• ACP connects a client to a coding agent. The client can be an editor, IDE, terminal UI, or another structured interface; the agent performs coding work and reports progress.
• It is not MCP. MCP connects an AI host to tools and data. ACP connects a user-facing client to an agent. A coding agent can use both.
• Sessions are first-class. Clients create, resume, prompt, cancel, and observe agent sessions rather than scraping terminal text.
• Capabilities and permissions are negotiated. The client advertises what it can provide; the agent asks for filesystem, terminal, or user-input actions through the protocol.
• Interop does not remove trust boundaries. The host still must sandbox execution, scope credentials, review writes, and log the actions that matter.

Why This Matters

Coding agents have spread across editors, terminals, cloud workspaces, and chat clients. Without a shared interface, every agent needs a separate integration for each client, and each client needs product-specific code for sessions, permissions, progress rendering, and cancellation.

ACP moves that boundary into a protocol. A compatible editor can expose a consistent interaction model while an agent can expose its work without a custom UI plugin for every surface. This is useful when teams want to keep their preferred editor while changing the underlying agent, or when they operate multiple coding agents under one control model.

It does not make agents interchangeable in practice. Model access, tool support, sandboxing, authentication, context assembly, and quality remain implementation-specific. ACP standardizes the conversation and control surface—not the agent’s intelligence or operational guarantees.

The Problem ACP Solves

Before ACP, editor integrations typically have three weak seams:

1. A proprietary plugin boundary. Each agent implements its own panel, progress UI, permission prompts, and session storage per editor.
2. Terminal scraping. A client launches a CLI and attempts to infer structured state from text output, which makes permissions, cancellation, and recovery brittle.
3. Uneven safety controls. One integration can show a file-write approval while another silently applies it because the agent and client lack a common request shape.

ACP gives client and agent a typed way to initialize, negotiate capabilities, manage a session, send prompts, stream updates, and request actions or permissions. It is especially relevant to coding agents because the client often owns the workspace view, diff review, terminal, and user approval UI.

How We Got Here

Provider SDKs first made it easier to build a coding agent, but they did not define how an editor should host it. Agent products then built product-specific IDE extensions and cloud clients. The Agent Client Protocol emerged to make the editor-to-agent boundary reusable, using JSON-RPC rather than an unstructured terminal stream.

The protocol’s stable wire version is currently v1. Its v2 work is a draft rather than a reason to assume v2 behavior is generally available. Treat the negotiated protocolVersion and advertised capabilities—not a package or schema artifact version—as the compatibility boundary.

Diagram: Coding-agent integration evolution

timeline
    title From bespoke plugins to an interoperable agent client
    section Early integrations
      Agent CLI : Text output in a terminal
      IDE extension : Product-specific UI and RPC
    section Shared boundary
      ACP v1 : Client-agent sessions and capabilities
      ACP v2 draft : Proposed next-generation protocol work

ACP makes the UI-to-agent contract portable; it does not standardize the agent’s model, sandbox, or tool policy.

What Is Agent Client Protocol?

ACP is a bidirectional JSON-RPC 2.0 protocol between two peers:

The client starts or connects to an agent, initializes the protocol, and creates a session. It sends a prompt into that session and receives session/update notifications while the agent works. The agent can request client-mediated actions, including permission-sensitive operations, rather than assuming it controls the client environment.

Diagram: ACP session boundary

sequenceDiagram
    actor D as Developer
    participant C as IDE / ACP client
    participant A as Coding agent
    participant W as Workspace and tools
    D->>C: Describe coding task
    C->>A: initialize + capabilities
    C->>A: session/new
    C->>A: session/prompt
    A-->>C: session/update (plan, edits, progress)
    A->>C: Permission or tool request
    C->>D: Present approval and diff
    D-->>C: Approve or reject
    C->>W: Execute allowed action
    W-->>A: Result
    A-->>C: Final response / stop reason

The agent proposes and coordinates work; the client mediates what can run in the user’s environment.

ACP vs MCP vs A2A

These names are easy to conflate because all may appear in an agentic coding stack.

For example, an IDE can use ACP to host a coding agent. That agent may use MCP to access an issue tracker and may delegate bounded work to another agent through a separate agent-to-agent mechanism. Each boundary needs its own policy.

Architecture

ACP is one control-plane edge inside a production coding-agent system.

Diagram: ACP in a production coding-agent stack

flowchart TB
    DEV[Developer] --> IDE[IDE / ACP client]
    IDE <--> ACP[ACP]
    ACP <--> AGENT[Coding agent]
    AGENT --> POLICY[Policy and approval checks]
    AGENT --> MODEL[Model provider]
    AGENT --> MCP[MCP client]
    MCP <--> TOOLS[MCP servers / developer tools]
    POLICY --> SANDBOX[Sandboxed terminal and workspace]
    IDE --> REVIEW[Diff and session review]

ACP carries the interactive agent session. MCP can carry the agent’s integrations; neither replaces a sandbox or authorization system.

Step-by-Step Flow

1. Select the client boundary. Decide which application owns the developer experience and the approval UI.
2. Start or connect to the agent. For a local agent, the client may spawn a process and speak ACP over stdin/stdout; deployment details remain agent-specific.
3. Initialize and negotiate. Exchange the wire protocol version and supported client/agent capabilities. Reject unsupported combinations explicitly.
4. Create or load a session. A session is the durable unit of a coding task; use a stable identifier only where the implementation supports resumption.
5. Send a bounded prompt. Include repository or workspace context through the client’s normal context policy, not by exposing every file or secret.
6. Render streamed updates. Distinguish model narration, progress, file proposals, terminal output, and permission prompts in the UI.
7. Mediate actions. Validate path, command, network, and credential rules before honoring any agent request.
8. Review the result. Show diffs, test output, and unresolved assumptions before merging or deploying.
9. Record the trace. Retain enough session and approval metadata to debug failures without storing sensitive source unnecessarily.

Real Production Example

An internal IDE client can keep its policy engine outside the model and outside the agent’s natural-language instructions.

type PermissionRequest = {
  kind: 'write_file' | 'run_command';
  path?: string;
  command?: string;
};

function mayApprove(request: PermissionRequest): boolean {
  if (request.kind === 'write_file') {
    return Boolean(request.path?.startsWith('/workspace/project/'));
  }

  if (request.kind === 'run_command') {
    return Boolean(
      request.command?.match(/^(npm test|npm run lint|git diff)(\s|$)/)
    );
  }

  return false;
}

async function handleAgentRequest(request: PermissionRequest) {
  if (!mayApprove(request)) {
    return { approved: false, reason: 'outside the session policy' };
  }

  // Still present the approved-in-principle request to the developer when
  // the operation writes files or executes a command.
  return await presentApprovalDialog(request);
}

This is intentionally not an ACP implementation. It illustrates the boundary ACP makes possible: structured agent requests can be evaluated by deterministic policy and then shown to a person. Do not rely on an agent’s own explanation of why a command is safe.

Design Decisions

Capability negotiation is not authorization

An advertised capability says that a peer knows how to represent an interaction. It does not grant that interaction. If a client supports terminal execution, the host must still decide whether a particular repository, command, environment variable, network destination, or credential is permitted.

Similarly, an agent’s ability to resume a session does not mean its previous authority should continue forever. Recheck time-sensitive authorization at the point of action.

Comparisons

ACP vs a vendor IDE extension

A vendor extension can offer a highly polished experience and exploit private product features quickly. It is often the right initial choice when an organization has standardized on one agent and one editor. The cost appears later: adopting a second agent, moving to a new editor, or building an internal review surface generally means rebuilding the whole integration boundary.

ACP is useful when the client and agent should evolve independently. A client can make its workspace, approval UI, session history, and accessibility behavior consistent, while agents expose structured session state rather than terminal-specific output. That does not mean every ACP agent provides the same capabilities. The client should discover what is supported and make absent support visible instead of inventing a fallback that changes safety semantics.

ACP vs terminal wrapping

Wrapping an agent CLI can be attractive because it needs no protocol adoption. It becomes fragile as soon as the UI needs reliable cancellation, resumable sessions, structured diffs, permission prompts, or distinction between a progress message and a command request. Parsing text is not a durable contract: an agent can change wording, add a progress bar, or localize output without changing its underlying behavior.

ACP does not eliminate the need to render terminal output, but it makes the message categories and session lifecycle explicit. A client can safely say “this is a file proposal,” “this is a request for user input,” or “this is a terminal tool request” only when the agent sends a structured representation. Keep a CLI wrapper for experiments and one-off local automation; move to ACP where the user experience or safety decision depends on structured state.

ACP vs MCP

ACP and MCP are complementary, and a production architecture should keep their controls separate. ACP addresses how a developer-facing client interacts with an agent. MCP addresses how an AI host discovers and invokes tools, resources, and prompts from capability servers. An ACP client should not assume that an MCP server is safe merely because an agent listed it, and an MCP host should not assume that an ACP approval prompt governs its server’s authorization.

Decision tree: ACP, MCP, or neither

Decision tree: Select the protocol boundary

flowchart TD
    A[What boundary needs standardization?] --> B{Developer client to coding agent?}
    B -->|Yes| C[Use ACP]
    B -->|No| D{AI host to external tool or data?}
    D -->|Yes| E[Use MCP]
    D -->|No| F{Agent delegation to another agent?}
    F -->|Yes| G[Use an agent-to-agent mechanism]
    F -->|No| H[Use a direct application API or deterministic workflow]

Choose a protocol for the seam you actually have; adding one at every layer creates operational surface without improving the product.

Adoption checklist

Before adopting ACP in a production client, verify these details with the exact client and agent versions you plan to ship:

1. Protocol version: Which wire version is negotiated, and which optional capabilities are required for your UX?
2. Session persistence: What is retained, where, for how long, and how is a resumed session re-authorized?
3. Filesystem model: Does the client or agent perform writes? Can paths escape the repository root through symlinks or worktrees?
4. Terminal model: Which process executes commands, under what user identity, with which network and credential access?
5. Permission rendering: Are requests shown before execution? Can organizational policy prohibit silent approval?
6. Tool composition: If the agent uses MCP, which servers and credentials are available in the specific session?
7. Failure behavior: What does the client show if the agent disconnects, the protocol version is incompatible, or a session cannot resume?
8. Auditability: Can an investigator reconstruct requested actions, approvals, edits, tests, and externally visible effects?

The checklist is intentionally more important than a compatibility badge. A client and agent can technically connect yet still be unsuitable for a regulated repository or a production deployment workflow.

Common Mistakes

1. Treating ACP as a generic agent-to-agent protocol. It is a client-to-agent interface; use a separate delegation mechanism for agent collaboration.
2. Confusing ACP with MCP. ACP governs the coding-agent session; MCP governs access to external capabilities.
3. Auto-approving because the client supports an action. Capability negotiation is not permission.
4. Passing an entire home directory as context. Scope the workspace and redact secrets before an agent session begins.
5. Using terminal output as the only audit record. Capture structured approvals, edits, command requests, outcomes, and stop reasons.
6. Assuming draft protocol features are stable. Pin to negotiated stable behavior and test upgrades in a compatibility suite.

Where It Breaks Down

ACP does not solve model quality, patch correctness, or the different ways agents interpret repository context. A compatible client can still host an agent that makes unsafe suggestions, misunderstands a codebase, or lacks the tool integration a workflow needs.

It also does not automatically make a remote agent safe. Remote execution adds identity, tenant isolation, data residency, network egress, artifact retention, and supply-chain questions. An ACP-compatible interface is not evidence that those controls exist.

When NOT to Use ACP

Skip ACP when:

1. You are building one tightly coupled product surface. A private in-process API can be simpler when neither the client nor agent needs to interoperate.
2. The task is a deterministic automation. Use CI, a script, or a workflow engine rather than an interactive agent session.
3. You only need tool integration. Use MCP or a direct API integration when no editor-to-agent session is involved.
4. Your agent cannot expose structured updates or permission requests. Fix that boundary first; wrapping terminal text gives weak safety and recovery semantics.

Running in Production

Decision tree: Should this use ACP?

flowchart TD
    A[Need an interactive client to host a coding agent?] -->|No| B[Use direct API, CI, or a workflow]
    A -->|Yes| C[Need portable client-agent integration?]
    C -->|No| D[Consider a product-specific integration]
    C -->|Yes| E[Use ACP with scoped permissions and a sandbox]
    E --> F[Use MCP separately for external tools and data]

Adopt ACP for the client-to-agent seam; add other protocols only for their specific seams.

Interview Questions

1. What problem does ACP solve that an IDE extension or terminal wrapper does not?
2. Why is ACP capability negotiation not authorization?
3. How does ACP differ from MCP in a coding-agent architecture?
4. Which actions should an ACP client require explicit approval for?
5. How would you safely resume a long-running coding-agent session?
6. What should the audit log capture for an ACP-mediated file write?

Related Guides

• AI Agents — the runtime loops and policy boundaries around agentic work.
• Tool Calling — structured model intent for invoking capabilities.
• Model Context Protocol — reusable tool, resource, and prompt integrations.
• Agent Skills — portable, task-specific procedures that an agent can load.
• Human in the Loop — approval and escalation patterns for high-impact actions.
• AI Security — least privilege, sandboxing, and prompt-injection controls.

Diagram: Learning path for coding-agent interoperability

flowchart LR
    A[AI agents] --> B[Tool calling]
    B --> C[MCP]
    C --> D[ACP]
    D --> E[Skills and approvals]
    E --> F[Secure production operation]

Learn the separate protocol boundaries before combining them in one coding-agent deployment.

FAQs

Is ACP only for IDEs?

No. IDEs are a primary use case, but any interactive client that can host a coding-agent session can implement ACP.

Does ACP standardize the model API?

No. The agent chooses and operates its model provider. ACP standardizes the client-to-agent interaction.

Does ACP replace MCP?

No. ACP is for the client-to-agent boundary; MCP is for hosts and external capability servers. They can be used in the same system.

Is ACP an authorization system?

No. It can represent permission requests, but the client, host, sandbox, and underlying services must enforce actual authorization.

Can an ACP session run remotely?

It can, but remote execution requires explicit identity, network, credential, tenancy, and retention controls outside the protocol.

How should a client handle an unsupported capability?

Negotiate capabilities during initialization and return a clear unsupported result rather than silently emulating unsafe behavior.

Should an ACP client trust agent-generated diffs?

No. Present diffs and test results for review; enforce repository and branch protections independently.

Is ACP v2 ready to target by default?

No. v2 is draft work. Target the stable negotiated protocol behavior supported by the client and agent you deploy.

References

• Agent Client Protocol — v1 overview
• Agent Client Protocol — v2 draft announcement
• Gemini CLI — ACP mode
• GitHub — Copilot in JetBrains Air
• GitHub — Copilot in Xcode’s coding assistant
• Model Context Protocol