Agent Client Protocol (ACP)

Use OpenHands CLI with code editors through the Agent Client Protocol

This feature is experimental and may have limitations. Please report any issues you encounter on OpenHands-CLI repo.

Prerequisites

Before using OpenHands CLI with ACP, you must first install and configure the CLI:

1. Install OpenHands CLI by following the CLI Mode installation instructions
2. Configure your LLM settings using the /settings command

The ACP integration will reuse the credentials and configuration from your CLI settings.

What is the Agent Client Protocol (ACP)?

The Agent Client Protocol (ACP) is a standardized communication protocol that enables code editors and IDEs to interact with AI agents. ACP defines how clients (like code editors) and agents (like OpenHands) communicate through a JSON-RPC 2.0 interface. For more details about the protocol, see the ACP documentation.

ACP Support in OpenHands CLI

OpenHands CLI implements the Agent Client Protocol, allowing you to use OpenHands directly within your code editor. When you configure your editor to use openhands acp, it will communicate with OpenHands through the standardized ACP interface.

OpenHands CLI currently supports the following ACP features:

✅ Implemented:

• Initialization - version negotiation and capability exchange
• Session Setup - creating new sessions and loading existing ones
• Content - including embedded content and resources
• Prompt Turns - sending prompts and receiving responses (permissions coming soon)
• Tool Calls - executing tools and returning results
• Agent Plan - sharing agent’s planned actions

🚧 Coming Soon:

• Confirmation - user authorization for tool calls
• Slash Commands - for changing confirmation mode

Feel free to open issues on the OpenHands-CLI repo if you have feature requests or encounter any problems.

ACP Integration

Zed IDE

Zed is a high-performance code editor with built-in support for the Agent Client Protocol.

To configure OpenHands CLI with Zed:

1. Ensure OpenHands CLI is installed and configured (see Prerequisites)

2. Open your Zed editor, use Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) to open the command palette, and search for agent: open settings

3. Then on the right side, click on + Add Agent and select Add Custom Agent

4. Add the following to the "agent_servers" field:

{
  "agent_servers": {
    "OpenHands": {
      "command": "uvx",
      "args": [
        "openhands",
        "acp"
      ],
      "env": {}
    }
  }
}

4. Save the file

5. You can now use OpenHands within Zed!

See Also

• CLI Mode - Learn about using OpenHands CLI interactively
• ACP Documentation - Full Agent Client Protocol specification
• Zed Documentation - Learn more about using Zed editor