What is ACP?
The Agent Communication Protocol (ACP) is a standardized protocol developed by JetBrains that enables seamless integration of AI agents with development environments. Key Features:- Bidirectional communication via JSON-RPC over stdio
- Tool execution capabilities (file operations, code analysis)
- Session management for maintaining conversation context
- Event notifications for real-time updates
What This Example Demonstrates
This example shows how to:- Create an ACP-compatible agent using Koog
- Connect the agent to IntelliJ IDEA
- Implement file operations (list, read, edit)
- Handle agent sessions and prompts
- Test agents using terminal clients
Agent Capabilities
The ACP agent provides three core tools:List Directory
Browse project file structure and list directory contents
Read File
Read and analyze source code files with full content access
Edit File
Make targeted code changes with precise string replacements
Prerequisites
- Java 17+
- IntelliJ IDEA 2024.3+ EAP with ACP support
- OpenAI API key
- Gradle (included in project)
Quick Start
Build the Agent
Create a distributable application:This creates an executable in
build/install/acp-agent/bin/Configure IntelliJ
Add your agent to IntelliJ’s ACP configuration:
- Open IntelliJ IDEA
- Navigate to AI Chat > Options > Configure ACP Agents
- Add the following JSON:
Implementation Details
Agent Entry Point
The main ACP agent initializes stdio transport and connects to the IDE:AcpAgent.kt
Koog Agent Creation
Create a Koog agent with file operation tools:KoogAgentSupport.kt
File Operation Tools
The agent uses Koog’s built-in file tools:KoogTools.kt
ListDirectoryTool
ListDirectoryTool
Lists all files and subdirectories at a given path.Arguments:
path: Absolute path to directory
ReadFileTool
ReadFileTool
Reads complete file contents.Arguments:
path: Absolute path to file
EditFileTool
EditFileTool
Makes targeted edits using string replacement.Arguments:
path: Absolute path to fileoldString: Exact text to replacenewString: Replacement text
Testing Without IDE
You can test the agent using terminal clients before IDE integration.Pipe Application
Uses in-process pipe for communication:PipeApp.kt
Process Application
Spawns agent as a subprocess:ProcessApp.kt
IntelliJ IDEA Configuration
Configuration File Location
IntelliJ stores ACP configurations in:- macOS
- Linux
- Windows
Configuration Format
acp-agents.json
command: Absolute path to agent executableargs: Command-line arguments (typically empty)env: Environment variables:OPENAI_API_KEY: Your OpenAI API key (required)ANTHROPIC_API_KEY: Your Anthropic API key (optional)OPENAI_BASE_URL: Custom OpenAI endpoint (optional)- Any custom environment variables your agent needs
Multiple Agent Configurations
You can configure multiple agents with different models or configurations:Example Use Cases
Code Review
Refactoring
Bug Fixing
Feature Addition
Customizing Your Agent
Change the LLM Model
Modify the agent creation to use different models:Add Custom Tools
Extend the agent with additional capabilities:Modify System Prompt
Customize the agent’s behavior and personality:Troubleshooting
Agent not appearing in IntelliJ
Agent not appearing in IntelliJ
Checks:
- Verify IntelliJ version is 2024.3+ EAP with ACP support
- Ensure configuration file path is correct
- Restart IntelliJ after adding configuration
- Check that the executable path is absolute (not relative)
- Verify executable has proper permissions (
chmod +x)
API Key Errors
API Key Errors
Solutions:
- Verify API key is valid and active
- Check environment variable name matches your configuration
- Ensure no extra spaces in the API key value
- Test the key with a simple curl command first
Agent Crashes or Timeouts
Agent Crashes or Timeouts
Debug steps:
- Run the agent manually from terminal to see error messages
- Check agent logs (if configured)
- Reduce
maxIterationsif hitting timeout - Verify file system permissions for ReadWrite operations
Tool Execution Failures
Tool Execution Failures
Common issues:
- File paths must be absolute, not relative
- Ensure ReadWrite permissions are set correctly
- Check that files exist before editing
- Verify string replacements match exactly (case-sensitive)
Project Structure
Source Code
View on GitHub
Explore the complete ACP agent implementation
Learn More
ACP Documentation
Official JetBrains ACP documentation
Custom Tools
Learn how to create custom tools
Next Steps
Spring Boot Integration
Deploy agents as REST APIs
Agent Strategies
Create custom agent behaviors