Agent Client Protocol (ACP)

Kiro CLI implements the Agent Client Protocol (ACP), an open standard that enables AI agents to work with any compatible editor. This means you can use Kiro's agentic capabilities in JetBrains IDEs, Zed, and other ACP-compatible editors.

ACP (Agent Client Protocol) standardizes how editors connect to AI agents, the same way the Language Server Protocol (LSP) standardized language server integration. Kiro CLI implements ACP so you can use it in a compatible editor without a custom integration for each agent. See Agent Client Protocol for the client and harness architecture.

Run Kiro as an ACP agent:

kiro-cli acp

To use a specific agent configuration:

kiro-cli acp --agent my-agent

The agent communicates over stdin/stdout using JSON-RPC 2.0. Configure your editor to spawn this command, and you're ready to go.

Which harness kiro-cli acp starts when nothing names one, and the flags that keep a client on V2, are covered under ACP clients. In Kiro CLI 2.36 or later, set the harness once with the acp.agentEngine setting, or pass --agent-engine in your editor's command arguments; the flag overrides the setting. Valid values are v1, v2, and v3. The chat.agentEngine setting applies to kiro-cli chat and does not change kiro-cli acp.

kiro-cli settings acp.agentEngine v3
kiro-cli acp --agent-engine=v2

To confirm the saved value, run kiro-cli settings acp.agentEngine. In Kiro CLI 3.2.0 or later, kiro-cli acp ignores a saved value that is not v1, v2, or v3 and, when the value came from your own settings, prints a warning on stderr that names the setting but not the value. For every kiro-cli acp flag, see CLI commands. For what changes when a client moves to the V3 harness, see Migrate an ACP client to CLI V3.

kiro-cli acp needs a signed-in Kiro account. In Kiro CLI 2.37 or later, if it starts while you are signed out, it answers the client's initialize request with one authentication method and returns an authentication-required error for every other request until you sign in.

• A client that declares terminal authentication in initialize is offered a terminal method named Log in to Kiro. Choosing it runs the Kiro sign-in in a terminal the client opens. Kiro accepts any of the three declaration forms: clientCapabilities.auth.terminal: true, the pre-standard clientCapabilities._meta["terminal-auth"]: true, or an ACP v2 capabilities.auth.terminal object.
• A client that declares none of these is offered a method that asks you to run kiro-cli login yourself.

After the sign-in finishes, reconnect from the client. The new kiro-cli acp process finds your credentials and starts the agent. To confirm, create a session: session/new succeeds instead of returning the authentication-required error.

Kiro CLI can be used as an ACP agent in any editor that supports the protocol.

JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, etc.) support ACP through AI Assistant. See the JetBrains ACP documentation for full details.

To add Kiro as a custom agent:

1. Open the AI Chat tool window
2. Click the settings button and select Add Custom Agent
3. Add the following to ~/.jetbrains/acp.json:

{
  "agent_servers": {
    "Kiro Agent": {
      "command": "/full/path/to/kiro-cli",
      "args": ["acp"]
    }
  }
}

The agent will appear in the AI Chat mode selector.

Zed supports ACP agents natively. See the Zed external agents documentation for full details. Add the following to your Zed settings (~/.config/zed/settings.json):

{
  "agent_servers": {
    "Kiro Agent": {
      "type": "custom",
      "command": "~/.local/bin/kiro-cli",
      "args": ["acp"],
      "env": {}
    }
  }
}

Select "Kiro Agent" from the agent picker in Zed's AI panel.

Any editor supporting ACP can integrate Kiro by spawning kiro-cli acp and communicating via JSON-RPC over stdio. See the ACP specification for protocol details.

Kiro CLI implements the following ACP methods, giving you access to session management, model selection, and streaming responses when using Kiro through any ACP-compatible editor.

The Kiro ACP agent advertises these capabilities during initialization:

• loadSession: true - Supports loading existing sessions
• promptCapabilities.image: true - Supports image content in prompts

The agent sends these session update types via session/notification:

For CLI v2, a content-filtered final response ends with stopReason: refusal rather than end_turn. ACP clients can present it as a refusal instead of normal completion, without exposing internal details.

Kiro extends the CLI v2 ACP server with custom methods (prefixed with _kiro.dev/ per the ACP spec) to expose Kiro-specific features like slash commands, MCP servers, and context compaction. Clients that don't support these extensions can safely ignore them — they're optional enhancements on the v2 server.

Here's how an ACP client initializes a connection with Kiro:

// Client sends initialize request
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "fs": {
        "readTextFile": true,
        "writeTextFile": true
      },
      "terminal": true
    },
    "clientInfo": {
      "name": "my-editor",
      "version": "1.0.0"
    }
  }
}

// Kiro responds with capabilities
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "loadSession": true,
      "promptCapabilities": {
        "image": true
      }
    },
    "agentInfo": {
      "name": "kiro-cli",
      "version": "1.5.0"
    }
  }
}

After initialization, create a session and start prompting:

// Create a new session
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/new",
  "params": {
    "cwd": "/home/user/my-project",
    "mcpServers": []
  }
}

// Send a prompt
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123",
    "content": [
      {
        "type": "text",
        "text": "Explain this codebase"
      }
    ]
  }
}

ACP agent logs are written to the standard Kiro log location:

Control log verbosity with environment variables:

KIRO_LOG_LEVEL=debug kiro-cli acp
KIRO_CHAT_LOG_FILE=/path/to/custom.log kiro-cli acp

• Agent Client Protocol (ACP) — how ACP connects clients to the unified agent harness
• Migrate an ACP client to CLI V3 — migrate from the CLI v2 ACP server
• Interactive Chat — uses ACP internally
• MCP Integration — MCP servers can be passed to ACP sessions
• CLI commands reference