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.

[friggeri]

@yazelin while I appreciate the suggestion, the goal of the Copilot SDK is to make it easy to integrate the Copilot CLI agentic loop into applications, not to serve as a universal SDK supporting other agentic loops. Will close this issue as won't fix.

[darthmolen]

For context on why this keeps coming up: the Copilot CLI (v0.0.410+) removed --headless --stdio support without deprecation, which breaks every version of copilot-sdk. The SDK internally spawns copilot --headless --stdio, and the CLI now exits with code 1.

I wasn't asking for "universal SDK supporting other agentic loops" — I was using @github/copilot-sdk with the Copilot CLI, exactly as intended. The CLI broke the SDK.

The only workaround is pinning to CLI v0.0.403 with --no-auto-update. I've filed issues on both repos:

• Breaking change: --headless --stdio removed without deprecation, breaks copilot-sdk and all downstream integrations copilot-cli#1606 — Breaking change without deprecation
• CLI v0.0.410+ auto-update breaks all SDK versions — --headless --stdio no longer accepted #530 — All SDK versions broken by CLI auto-update

The "wontfix" decision here means the SDK team won't adapt to ACP, and the CLI team already removed the old protocol. SDK users are caught in the middle.

[offbeatport]

Hey everyone!

Since GitHub confirmed the Copilot SDK isn’t intended to support other adapters or agentic loops, I wanted to share an open-source solution I’ve built that covers this use case:

https://github.com/offbeatport/meshaway

Meshaway is a bridge process that lets you plug ACP agents (Gemini, OpenCode etc.) into your existing Copilot SDK setup without changing your code. The focus is on keeping it simple, practical, and easy to drop into existing workflows.

To use it:

Install with Homebrew

brew tap offbeatport/tap
brew install meshaway

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  cliPath: "meshaway", // or path to binary, e.g. "./release/meshaway"
  cliArgs: [
    "bridge",
    "--agent",
    "gemini",
    "--agent-args",
    "--experimental-acp --model gemini-2.5-flash-lite",
  ],
});

await client.start();
const session = await client.createSession();
await session.send({ prompt: "Hello!" });

There are also other examples here:
https://github.com/offbeatport/meshaway/tree/main/examples

It also comes with an optional web interface (hub) for debugging sessions and experimenting with agents.

Feedback, issues, and contributions are very welcome.