Use the ACP Client

With the ACP Client extension, you can chat with AI agents that understand your codebase and perform actions on your behalf, such as editing files, running commands, or triggering builds.

This topic walks you through setting up and using the ACP Client extension from activating the extension to having a productive chat session with an agent.

Prerequisites

• Activate the ACP Client extension in the Extensions mode. For more information about extensions, see Activate extensions.
• Recommended: Activate and set up the MCP Server extension if you want the agent to trigger Qt Creator actions such as building or running your project. For more information, see Set up Qt Creator MCP server.

Configure an agent

Before opening a chat, configure in Preferences which agent you want to talk to. You can either pick one of the preconfigured agents or define a custom one.

Preconfigured agents

To set up a preconfigured agent:

1. Go to Preferences > AI > ACP Servers.
2. Select Add.
3. In Template, select a preconfigured agent to use it with its default settings.
4. Select Apply to save.

Custom agents

To set up a custom agent:

1. Ensure the agent process you intend to use is installed and reachable on your machine or network.
2. Go to Preferences > AI > ACP Servers.
3. Select Add.
4. In Template, select Custom.
5. In Name, specify a name for your agent configuration.
6. In Launch command, specify the command to launch the ACP server process.
7. In Launch arguments, specify command-line arguments to pass when launching the ACP server process.
8. In Environment Changes, select Change to add any environment variable changes needed for the agent process.
9. Select Apply to save.

Open the ACP chat window

In Edit mode, you can open the ACP chat window in the following ways:

• Go to Tools > ACP Client > Show Agentic AI Chat in Side Panel.
• Select in the editor toolbar when you have a file open.

Connect to an ACP server

After you open the chat window for a project, connect to an ACP server.

To connect to the ACP server:

1. In the Server drop-down, select the agent you configured.
2. In Working directory, verify or change the directory that the agent should treat as the project root. This is set to the active project's root directory by default.
3. Select Connect.

Qt Creator starts the agent process and establishes the ACP connection.

To start a new session, select in the top right corner of the chat window and connect to a server.

Chat window toolbar

Once connected, the toolbar at the bottom of the chat window shows controls that you can adjust at any time during a session.

The different configuration options in the toolbar depend on the selected agent. To view more information about an option, hover over it to see its tooltip.

Chat with the agent

Type your message in the input field at the bottom of the chat window and select Send or Enter.

To insert a command to your message, select / and select a command from the list.

Context in messages

Qt Creator automatically attaches the current editor context to every message, so you can use natural references such as:

• Explain the current code.
• Refactor the selected block to use a range-based for loop.
• Why does the build fail? Fix it.

  Note: This requires the MCP server extension so the agent can invoke the build system and read compiler output.

• Add unit tests for the function at the cursor.
• Review the visible code and suggest improvements.

To add more context to your message manually, select > Add file or Add remote file in Context.

Agent's responses

The agent's reply appears in the chat window.

If the agent proposes file edits, you can review them in the chat window. Depending on the selected Mode, you might need to allow the agent to apply them.

Typical workflows

You can use the ACP Client for a wide range of tasks. Here are some example workflows to get you started.

Explain and explore

1. Open any source file.
2. Set Mode to Plan Mode to prevent accidental edits.
3. Ask: Walk me through what this class does and identify any potential issues.
4. Read the agent's analysis in the chat history.

Refactor with review

1. Select the code you want to change.
2. Set Mode to Default.
3. Ask: Extract the selected code into a separate function called processInput.
4. Review the proposed changes.

Build and fix

1. Make sure both the ACP Client and the MCP Server extensions are active.
2. Set Mode to Accept Edits.
3. Ask: Build the project and fix any compiler errors.
4. The agent triggers a build through the MCP server, reads the output, and applies fixes. Watch the progress in the chat history.