// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-how-to-use-acp-client.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-ai

    \title Use the ACP Client

    With the \uicontrol {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.

    \section1 Prerequisites

    \list
        \li Activate the \uicontrol {ACP Client} extension in \preferences >
            \uicontrol Extensions > \uicontrol Browse. For more information
            about extensions, see \l {Activate extensions}.
        \li Recommended: Activate and set up the \uicontrol {MCP Server}
            extension if you want the agent to trigger \QC actions such as
            building or running your project. For more information, see
            \l {Set up \QC MCP server}.
    \endlist

    \section1 Configure an agent

    Before opening a chat, select an agent in \preferences. You can either pick
    one of the preconfigured agents or define a custom one.

    \section2 Preconfigured agents

    To set up a preconfigured agent:

    \list 1
        \li Go to \preferences > \uicontrol AI > \uicontrol {ACP Servers}.
        \li Select \uicontrol {Add}.
        \li In \uicontrol {Template}, select a preconfigured agent to use
            it with its default settings.
        \li Select \uicontrol Apply to save.
    \endlist

    \section2 Custom agents

    \image {qtcreator-acp-preferences-custom.webp} {ACP Servers settings for a custom agent}

    To set up a custom agent:

    \list 1
        \li Install the AI agent on the computer or network and check the
            connection to it.
        \li Go to \preferences > \uicontrol AI > \uicontrol {ACP Servers}.
        \li Select \uicontrol {Add}.
        \li In \uicontrol {Template}, select \uicontrol {Custom}.
        \li In \uicontrol {Name}, specify a name for your agent configuration.
        \li In \uicontrol {Executable}, specify the executable to launch
            the ACP server process.
        \li In \uicontrol {Arguments}, specify command-line arguments
            to pass when launching the ACP server process.
        \li In \uicontrol {Environment Changes}, select \uicontrol {Change} to
            add any environment variable changes needed for the agent process.
        \li Select \uicontrol Apply to save.
    \endlist

    \section2 Connect to agents

    The contents of the ACP registry determine the method to connect to a
    particular agent:

    \list
        \li \c {binary} packages are used directly without dependencies.
        \li \c {npx} Node.js packages require that you install \l {Node.js}.
        \li \c {uvx} Python packages require that you install the \l uv
            package manager and Python.
    \endlist

    \note Restart \QC after you install dependencies.

    \section3 npx

    To check that you have Node.js, enter \c {node --version} on the command line.

    If the AI agent cannot find the \c npx binary it uses to run the Claude
    agent even though the folder is in the PATH, add the \c npx directory to
    the path in \preferences > \uicontrol Environment > \uicontrol System. In
    \uicontrol Environment, select \uicontrol Change and add
    \c {PATH+=<full-path-to-folder}).

    \section3 Claude CLI

    You might need to install more dependencies to use some agents. For example,
    to authenticate to Claude, you must also install \l {Claude: Quick Start}
    {Claude Code CLI}. To check that you have it, enter \c {claude --version} on
    the command line.

    \section1 Open the ACP chat window

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

    \list
        \li Go to \uicontrol Tools > \uicontrol {ACP Client} >
            \uicontrol {Show Agentic AI Chat in Side Panel}.
        \li Select \inlineimage {icons/message.png} {Show Agentic AI Chat in Side Panel}
            (\uicontrol {Show Agentic AI Chat in Side Panel})
            in the editor toolbar when you have a file open.
    \endlist

    \section1 Connect to an ACP server

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

    \image {qtcreator-acp-connect.webp} {Connecting to the ACP server}

    To connect to the ACP server:

    \list 1
        \li Select the agent you configured.
        \li Select \uicontrol Connect.
    \endlist

    If an agent is not listed in \uicontrol {Choose AI Agent}, select
    \uicontrol {Manage Agents} to add it.

    \QC starts the agent process and establishes the ACP connection.

    To start a new session, select \inlineimage {icons/plus.png} {Add Chat}
    \uicontrol {Add Chat} and connect to a server.

    \section3 Inspect ACP communication

    An ACP Client extension sends messages (\e requests) to an ACP server and
    receives responses that have the requested information if the server is
    capable of handling the requests. To inspect the communication between the
    extension and ACP servers, go to \uicontrol Tools > \uicontrol {ACP Client} >
    \uicontrol {Inspect ACP Client}.

    \image qtcreator-acp-client-inspector.webp {ACP Client Inspector dialog}

    In \uicontrol {ACP Client}, select an ACP server to show a list of events.
    Select an event to view the client request in \uicontrol {Client Message}
    and the server response in \uicontrol {Server Message}.

    To remove old entries, select \uicontrol Clear.

    To save messages as a file, select \uicontrol Save.

    \section1 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.

    \image {qtcreator-acp-toolbar.webp} {ACP Chat toolbar}

    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.

    \section1 Chat with the agent

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

    \image {qtcreator-acp-chat.webp} {Chatting with the agent}

    To insert a command to your message, select \uicontrol {/} and select a
    command from the list.

    \section2 Context in messages

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

    \list
        \li \e {Explain the current code.}
        \li \e {Refactor the selected block to use a range-based for loop.}
        \li \e {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.
        \li \e {Add unit tests for the function at the cursor.}
        \li \e {Review the visible code and suggest improvements.}
    \endlist

    To add more context to your message manually, select
    \inlineimage {icons/plus.png}{Add content} > \uicontrol {Add file} or
    \uicontrol {Add remote file} in \uicontrol Context.

    \section2 Agent's responses

    The agent's reply appears in the chat window.

    \image {qtcreator-acp-file-edits.webp} {Agent-proposed file edits}

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

    \section1 Typical workflows

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

    \section2 Explain and explore

    \list 1
        \li Open any source file.
        \li Set \uicontrol Mode to \uicontrol {Plan Mode} to prevent
            accidental edits.
        \li Ask: \e {Walk me through what this class does and identify any
            potential issues.}
        \li Read the agent's analysis in the chat history.
    \endlist

    \section2 Refactor with review

    \list 1
        \li Select the code you want to change.
        \li Set \uicontrol Mode to \uicontrol Default.
        \li Ask: \e {Extract the selected code into a separate function called
            \c processInput.}
        \li Review the proposed changes.
    \endlist

    \section2 Build and fix

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

    \sa {Activate extensions}, {Use AI}{How to: Use AI}, {Qt for Python}
*/
