Feature Request: Support ACP (Agent Client Protocol) Compatible CLIs

[yazelin]

Summary

Add native support for the Agent Client Protocol (ACP) to allow Copilot SDK to connect directly to ACP-compatible agents like Gemini CLI, without requiring a protocol translation proxy.

Problem

Currently, when using cliPath to specify a custom CLI (e.g., gemini), the SDK fails because it sends Copilot-specific CLI arguments (--headless, --stdio, --log-level) that ACP-compatible CLIs don't recognize.

// This doesn't work with Gemini CLI
const client = new CopilotClient({
  cliPath: "gemini"
});

Error:

Unknown arguments: server, log-level, logLevel, stdio

Root Cause: Protocol Incompatibility

Copilot SDK and ACP use different JSON-RPC method names and initialization flows:

Feature	Copilot SDK Protocol	ACP Protocol
Initialize	ping	initialize
Create Session	session.create	session/new
Send Message	session.send	session/prompt
Cancel	N/A	session/cancel
CLI Arguments	--headless --stdio --log-level	--experimental-acp (Gemini)

Current Workaround

Users must build a protocol translation proxy that:

1. Accepts Copilot SDK protocol over stdio
2. Translates to ACP protocol
3. Spawns and communicates with the ACP agent

Example implementation: claude-code-acp-py (PyPI) - A Python proxy that bridges Copilot SDK to ACP-compatible backends (Gemini CLI, Claude Code ACP, etc.)

This adds complexity and maintenance burden.

Proposed Solution

Add an option to specify the protocol type when creating a client:

// Option 1: New protocol parameter
const client = new CopilotClient({
  cliPath: "gemini",
  protocol: "acp",  // or "copilot" (default)
  cliArgs: ["--experimental-acp"]
});

// Option 2: Auto-detect based on initialization response
const client = new CopilotClient({
  cliPath: "gemini",
  cliArgs: ["--experimental-acp"],
  autoDetectProtocol: true
});

Use Cases

1. Gemini CLI Integration: Use gemini --experimental-acp directly with Copilot SDK
2. Claude Code ACP: Connect to claude-code-acp implementations
3. Custom Agents: Support any ACP-compatible agent without proxy overhead
4. Ecosystem Interoperability: ACP is becoming a standard for AI agent communication (supported by Zed, Neovim, etc.)

References

• ACP Specification
• ACP GitHub
• Gemini CLI ACP Support - Lists Gemini CLI as ACP-compatible
• Claude Code ACP Request (anthropics/claude-code#6686) - 434+ upvotes showing community demand
• claude-code-acp-py - Protocol translation proxy (workaround implementation)

Environment

• SDK: Node.js / Python / Go / .NET (all affected)
• Tested with: Gemini CLI v1.x with --experimental-acp

[github-actions]

Thank you for opening this feature request, @yazelin!

This is a well-documented enhancement proposal for supporting ACP (Agent Client Protocol) compatible CLIs. I've applied the following labels:

• enhancement — This is a feature request for new functionality
• sdk/dotnet, sdk/go, sdk/nodejs, sdk/python — This affects all SDK implementations

The proposal includes clear problem description, root cause analysis, proposed solutions, and external references. The team will review the feasibility of adding ACP protocol support as an alternative to the current Copilot CLI JSON-RPC protocol.

AI generated by Issue Triage Agent

[yazelin]

Implementation Progress Update

I've submitted PR #379 with initial ACP protocol support for the Node.js SDK.

✅ Completed (PR #379)

Feature	Status
protocol: "acp" option in CopilotClientOptions	✅
NDJSON transport (ACP wire format)	✅
Method translation: ping → initialize	✅
Method translation: session.create → session/new	✅
Method translation: session.send → session/prompt	✅
Notification mapping: session/update → session.event	✅
Skip --headless --stdio --log-level for ACP mode	✅
Handle Gemini's stopReason in response	✅
Unit tests (43 tests)	✅
E2E tests with Gemini CLI	✅

🚧 In Progress

Feature	Status
Tool calls support (session/request_permission)	🚧 Working on it

📋 Planned

Feature	Notes
autoDetectProtocol option	Nice-to-have
Python SDK	After Node.js is complete
Go SDK	After Node.js is complete
.NET SDK	After Node.js is complete

Testing

Successfully tested with:

• Gemini CLI (gemini --experimental-acp)
• Real-world demo app: copilot-sdk-demo

const client = new CopilotClient({
  cliPath: "gemini",
  cliArgs: ["--experimental-acp"],
  protocol: "acp"
});

[yazelin]

Implementation Complete 🎉

PR #379 now includes full ACP support:

Features Implemented

Feature	Status
Protocol option ("acp" | "copilot")	✅
NDJSON transport	✅
Method translation (ping, session.create, session.send)	✅
Streaming events (assistant.message_delta)	✅
Session idle handling (Gemini stopReason)	✅
Tool calls (tool.execution_start/complete)	✅
Permission requests (session/request_permission)	✅

Test Coverage

• 53 unit tests (transport, mapper, adapter)
• 14 E2E tests with actual Gemini CLI

Usage

const client = new CopilotClient({
  cliPath: "gemini",
  cliArgs: ["--experimental-acp"],
  protocol: "acp"
});

await client.start();
const session = await client.createSession();

session.on((event) => {
  if (event.type === "assistant.message_delta") {
    process.stdout.write(event.data.deltaContent);
  } else if (event.type === "tool.execution_start") {
    console.log(`Tool: ${event.data.toolName}`);
  }
});

await session.send({ prompt: "Hello!" });

See PR #379 for full details.