Agent Client Protocol (ACP)

AI Assistant supports the Agent Client Protocol (ACP), allowing you to connect external AI agents and use them directly in the AI Chat. ACP defines a standard communication interface, so any compatible agent can be added and used right away without requiring a custom integration.

What is needed to configure an agent through ACP

To connect to an agent through ACP, you need:

An ACP-compatible agent executable – typically downloaded as a binary from the agent's developer or built from its public repository.
An ACP configuration file – this file tells AI Assistant where the agent is located and how to launch it. The acp.json file is created automatically when you begin configuring an agent.

Where to get an agent

As a starting point, you can explore the list of ACP-compatible agents available on the official ACP website. Each agent page provides download instructions and the required configuration details.

Configure an ACP-compatible agent

To add an agent that will be available for use in AI Chat, do the following:

Open the AI Chat tool window.
Click the button in the upper-right corner of the tool window and select Configure ACP Agents.
Choosing this option creates the acp.json file at ~/.jetbrains/acp.json and opens it for editing, where you must provide the configuration details.
Populate the configuration file with the details of your agent. You can add multiple agents if needed. The configuration must follow this format:
{ "agent_servers": { "Example Agent": { "command": "/path/to/agent", "args": [ "acp" ], "env": { "API_KEY": "your-api-key-here" } } } }
- agent_servers – the top-level object that contains all configured agents. Each key inside this object is the display name of the agent as it will appear in AI Chat.
- Example Agent – the name of the agent used for display and identification.
- command – the path to the agent executable. AI Assistant launches this file as a subprocess.
- args – an array of command-line arguments passed to the agent when it starts.
- env – a collection of environment variables set for the agent process.
  Although the example includes an API_KEY, most agents do not require one. Instead, you are typically expected to run the agent in a terminal and authenticate there using the provided instructions. The credentials you enter are saved in your user configuration, so the agent will no longer ask for them the next time it is started.
Refer to your agent's documentation to ensure that you use the correct parameter values.
Once the configuration is complete, the agent becomes available for selection in AI chat. Added agents are indicated by the icon.
To use the agent, enter a prompt and send it.

Collect ACP logs

To collect logs for configured agents, click the button in the upper-right corner of the AI Chat tool window and select Get ACP Logs. This will download an archive containing the logs.

Configuration example

This section shows an example of what an ACP configuration file may look like:

            {
                "agent_servers": {
                    "Auggie": {
                        "command": "/Users/John.Doe/.local/bin/auggie",
                        "args": ["--acp"]
                    },
                    "OpenCode": {
                        "command": "/Users/John.Doe/.opencode/bin/opencode",
                        "args": ["acp"]
                    },
                    "Stakpak": {
                        "command": "/Users/John.Doe/Downloads/stakpak",
                        "args": ["acp"]
                    }
                }
            }
        

Troubleshooting

This section contains troubleshooting tips for ACP-compatible agents.

Added agent is not shown in the list

Agents added to the acp.json file should become available in AI Chat right away. If an agent does not appear in the list:

Check that the acp.json file is correctly formatted.
Restart the IDE.

Agent fails to start

If the agent fails to start, try the following:

Ensure that all provided parameters have the correct values, as different agents may require different keys or arguments.
Use the full path to the agent executable in the command parameter.
On Windows with WSL, adjust the configuration as follows:
{ "agent_servers": { "Agent": { "command": "wsl.exe", "args": ["-e", "agent path", "..."] } } }
If the agent supports a console mode, try running it manually from a terminal to verify that it works.

If the issue persists, do the following:

Collect the logs.
Copy your acp.json configuration (remove any sensitive information before copying).
Take screenshots or record a short video illustrating the issue.
Create an issue in YouTrack.
Attach the screenshots, logs, and the configuration file to the issue.

05 December 2025