{"slug": "how-to-use-ai-agents-in-intellij-idea-with-acp", "title": "How to Use AI Agents in IntelliJ IDEA With ACP", "summary": "JetBrains' IntelliJ IDEA now supports AI agents through the Agent Client Protocol (ACP), a standardized contract between the IDE and coding agents, with bundled agents including Codex, Claude Agent, and Junie, and additional options available via the ACP Registry. ACP, developed in collaboration with Zed, allows seamless swapping of agents without changing IDE integration, as each agent maintains its own models, tools, and behavior behind a common boundary.", "body_md": "## IntelliJ IDEA\n\nIntelliJ IDEA – the Leading IDE for Professional Development in Java and Kotlin\n\n[AI](/idea/category/ai/)\n\n[AI Assistant](/idea/category/ai-assistant/)\n\n[Tutorials](/idea/category/tutorials/)\n\n# How to Use AI Agents in IntelliJ IDEA With ACP\n\nThe [Agent Client Protocol (ACP)](https://agentclientprotocol.com/protocol/overview) defines a common contract between a client – like IntelliJ IDEA – and an agent. IntelliJ IDEA already includes several ACP-compatible agents: Codex, Claude Agent, and Junie. Beyond these bundled options, the ACP Registry provides more choices, and teams can register internal or unlisted agents through acp.json.\n\nThe key idea is the **boundary**. IntelliJ IDEA remains the environment where you navigate the project, inspect code, and review changes. Across the ACP connection, each agent maintains its own models, behavior, authentication, and agent-side tools.\n\nThis makes the replaceable unit larger than an LLM. An ACP-compatible agent includes the full harness around the model: its planning logic, tools, model-routing behavior, and observability. Because ACP standardizes the boundary between the IDE and the agent, you can swap one agent for another smoothly, without changing how IntelliJ IDEA integrates with it.\n\n**ACP in a nutshell**\n\nACP is often described as the LSP (Language Server Protocol) for coding agents. The analogy works because the integration problem is similar.\n\nBefore the LSP, supporting each language meant writing a separate editor integration. The [LSP](https://blog.jetbrains.com/idea/2026/08/intellij-idea-goes-lsp/) replaced that matrix with a single contract.\n\nACP applies the same idea to the connection between an editor or IDE and a coding agent. Any ACP-compatible agent can connect without requiring a bespoke plugin or private API for each pairing.\n\nACP originated from a [collaboration between JetBrains and Zed](https://blog.jetbrains.com/ai/2025/10/jetbrains-zed-open-interoperability-for-ai-coding-agents-in-your-ide/), with both JetBrains IDEs and Zed targeted as clients from the start.\n\nFor local agents, IntelliJ IDEA starts a subprocess and communicates with it via JSON-RPC over standard input and output. During initialization, the IDE and the agent negotiate protocol versions and capabilities. Once connected, prompts flow to the agent, while progress updates, file operations, and permission requests return to the IDE.\n\nAgents can still behave differently under that shared contract. During initialization, each one declares the optional capabilities it supports. Plans, modes, slash commands, session loading, terminal operations, and other features can differ between agents.\n\nACP carries the interaction between IntelliJ IDEA and the agent. Additional tools and context can reach the agent through MCP (Model Context Protocol), including user-configured servers and the integrated IntelliJ MCP server.\n\n# Start with an available agent\n\nIntelliJ IDEA ships with several agents that require no manual ACP configuration, including Codex, Claude Agent, and Junie. Choose one and describe the task you want it to handle.\n\nEach agent has its own workflow style, which may include a planning mode, slash commands, or a particular authentication flow. ACP lets IntelliJ IDEA host that interaction through a shared contract while preserving those differences.\n\nAsk the agent to make a small change. After it edits a file, AI Chat shows the changed file in the conversation. Click it to open the diff in the editor beside the chat and inspect exactly what changed.\n\nThat edit-and-review loop is the part worth keeping. If you switch agents later, having the loop inside the IDE prevents you from having to move the project or review changes in a separate tool.\n\n# Install an agent from the ACP Registry\n\nThe [ACP Registry](https://agentclientprotocol.com/registry) contains additional ACP-compatible agents, together with the metadata IntelliJ IDEA needs to install them.\n\nIn IntelliJ IDEA, open *Settings | Tools | AI Assistant | Agents* and then choose an agent from the registry. The [current ACP documentation](https://www.jetbrains.com/help/ai-assistant/acp.html#install-agent-from-registry) describes the complete installation flow.\n\nThe agent’s configuration view also lets you expose the MCP servers configured in AI Assistant, the integrated IntelliJ MCP server, or both.\n\nIntelliJ IDEA downloads the agent files when you apply the settings. The first session may ask you to authenticate using a method supported by that agent.\n\nThe registry also supplies the metadata used for updates and uninstallation. These operations remain in the *Agents* settings, so adding an agent does not require maintaining another IDE plugin.\n\nEach registry agent retains its own license, service, credentials, and privacy terms. Check these details before granting repository access.\n\n# Connect a custom agent with acp.json\n\nRegistry agents are intended for broad distribution. An internal agent, however, often has a narrower role and should stay inside the company.\n\nIf an internal agent implements ACP, register it in ~/.jetbrains/acp.json. IntelliJ IDEA provides an *Add Custom Agent* action that creates and opens this file, but you can also edit the file directly.\n\nThe configuration below registers a hypothetical company migration agent:\n\n```\n{\n  \"agent_servers\": {\n    \"Company Migration Agent\": {\n      \"command\": \"/opt/company/bin/migration-agent\",\n      \"args\": [\"acp\"]\n    }\n  }\n}\n```\n\nEach key under agent_servers becomes the agent’s display name. The command value must contain the full path to the executable that IntelliJ IDEA will start. Place the arguments required to activate that agent’s ACP mode in args; the exact values come from the agent’s documentation.\n\nUse env when the process needs environment variables. Many agents expect you to authenticate through their CLI first and reuse credentials stored in the agent’s user configuration. If an agent accepts an API key through env, follow its documentation and avoid committing the file or its secrets to a repository.\n\nSave `acp.json`\n\nand then select the configured agent in IntelliJ IDEA.\n\nIf any ACP-compatible agents are already installed on the machine, the IDE will detect them and offer to add them to the configuration.\n\n# Why use more than one agent?\n\nTeams may want different agents for different kinds of work. ACP gives those agents a common way to connect to IntelliJ IDEA:\n\n- Connecting an ACP-compatible agent through `\n`acp.json`\n\n` avoids developing and maintaining a separate IntelliJ IDEA plugin. - Navigation, editing, and diff review remain in IntelliJ IDEA while developers choose the agent for the work.\n- If an agent’s service or model provider is unavailable, developers can switch to another configured agent and continue working in the same IntelliJ IDEA project.\n\n# Keep the IDE, choose the agent\n\nUse an agent already available in IntelliJ IDEA, install one from the ACP Registry, or register an internal agent in `acp.json`\n\n.\n\nACP turns the coding agent from an IDE commitment into a replaceable choice you can revisit at any time.\n\n#### Subscribe to IntelliJ IDEA Blog updates", "url": "https://wpnews.pro/news/how-to-use-ai-agents-in-intellij-idea-with-acp", "canonical_source": "https://blog.jetbrains.com/idea/2026/08/how-to-use-ai-agents-in-intellij-idea-with-acp/", "published_at": "2026-08-12 14:50:50+00:00", "updated_at": "2026-08-12 15:52:44.832816+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["JetBrains", "IntelliJ IDEA", "Agent Client Protocol", "Codex", "Claude Agent", "Junie", "Zed", "MCP"], "alternates": {"html": "https://wpnews.pro/news/how-to-use-ai-agents-in-intellij-idea-with-acp", "markdown": "https://wpnews.pro/news/how-to-use-ai-agents-in-intellij-idea-with-acp.md", "text": "https://wpnews.pro/news/how-to-use-ai-agents-in-intellij-idea-with-acp.txt", "jsonld": "https://wpnews.pro/news/how-to-use-ai-agents-in-intellij-idea-with-acp.jsonld"}}