External Agents

Connect different AI agents, configure them as Profiles in Huabu.

What is an external agent?

External agents are AI agents outside Huabu's built-in agent system. Huabu currently starts local ACP-compatible agents, connects to them over ACP, and associates each with a working directory and chat thread. Model access, authentication, tools, permissions, and usage charges remain with the agent or its provider.

Access to your Space

A connected external agent does more than chat. Like Huabu Agent, it can read the current Space — its nodes, their content, and layout — and change it by creating, editing, connecting, moving, or deleting nodes. This access is scoped to the single Space and conversation the agent is attached to while that conversation runs; it does not extend to your other Spaces.

An external agent may ask for your approval before it acts. The request appears as a Permission required state on its Agent Node. You can also review and undo the changes an agent makes, just as you would for Huabu Agent.

Before you start

Prepare the agent on the same computer that runs Huabu:

Install an ACP-compatible agent. Huabu automatically detects these eight ACP-capable agent commands or adapters after installation: GitHub Copilot, Claude Agent, Gemini, Codex, Qwen Code, Kimi Code, OpenCode, and Cursor. For any other ACP-compatible agent, select Custom command and enter its complete ACP launch command, such as /path/to/my-agent --acp. Use the command documented by that agent.
Sign in and accept any first-run prompts. Open a normal terminal, run the agent once, and complete its authentication or provider setup. Huabu cannot complete an interactive sign-in for a background agent process.
Ensure Huabu can find the agent. The agent command must be on the operating system's PATH environment variable when Huabu starts. Restart Huabu after installing the agent or changing PATH. If the command is still unavailable, use Custom command with its absolute executable path.

Create a Profile

A Profile is Huabu's saved connection to one external agent in one working directory. Open Settings () > External Agents, select Add agent, and complete these fields:

Field	What to choose
Preset	Choose a Preset to give the agent a ready-made role and workflow, including any required tools, configuration, and setup. Leave it set to None to use the agent as installed. See Understand Presets.
Agent	Installed agents appear first. Agents that are not installed appear in a disabled Not installed section, followed by Custom command. Selecting a Preset filters the list to agents supported by that Preset.
Auto-approve all tool calls	Optional. With no Preset, this appears when Huabu knows the selected agent’s auto-approval option. Enable it only when you trust the agent and the working directory.
Working directory	The local project folder used as the agent process working directory. Each Profile can point to a different folder.
Display name	Optional. Huabu derives a name from the agent or Preset and the working-directory folder when you leave it empty.
Icon	Choose one of four Profile icon shapes and four colors to identify this External Agent in Agent menus and on Agent Nodes. Huabu assigns a Profile icon automatically, and you can change it later.

See External Agent Profile icons to preview the available shapes and colors.

With no Preset, select Create profile. The Profile is ready to use immediately. Choose Custom command at the end of the Agent menu when you need an absolute path, extra flags, or an ACP agent Huabu does not detect. Enter the complete command Huabu should launch.

Understand Presets

A Preset is a ready-made workflow for a specific task. It gives an external agent a specialized role, instructions, and tools, and may configure the working directory for that workflow. A Preset is not a model and does not install the external agent itself.

The first release includes the following Presets. Their additional requirements apply alongside the installed and authenticated external agent described above.

Preset	What it does	Additional requirements
paper-reviewer	Provides a paper-review role and workflow for discussing academic papers and drafting review responses.	None. It does not install npm tools or skills.
html-slides-maker	Creates static HTML presentations and optional technical diagrams.	Node.js with `npx` available on the `PATH`, plus network access to GitHub during setup so Huabu can install the required skills.
hackmd-publisher	Turns selected Space material into a HackMD document and writes the published URL back to Huabu.	A HackMD API token, Node.js with `npm` and `npx` available on the `PATH`, access to a working npm registry, and network access to GitHub during setup.

On macOS, Windows, and Linux, npm and npx are normally installed with Node.js. Verify that node --version, npm --version, and npx --version work in a normal terminal, then restart Huabu after installing Node.js or changing the PATH. A company npm mirror is supported as long as it can provide the packages required by the Preset.

Without a Preset	With a Preset
Huabu launches the selected agent with its standard ACP command.	Huabu launches the selected agent with the Preset's managed instructions and tools.
You can select any installed recognized agent or enter a Custom command.	You can select only an installed agent supported by that Preset. Custom command is unavailable.
The Profile is ready as soon as it is created.	Huabu prepares the working directory before the Profile becomes available.
No Preset-specific configuration is required.	The Preset may request tokens or other configuration. Secret values are stored securely and are never displayed again.

After selecting a Preset, complete any fields shown directly below it, choose an available Agent and a working directory, then select Create and set up. Setup continues from the External Agents list. When setup finishes successfully, the setup status and action disappear and the Profile becomes available in Chat. If setup fails, the Profile remains in the list so you can fix its configuration and retry.

Preset configuration belongs to the Preset and is shared by Profiles created from the same Preset. The working directory and display name still belong to each individual Profile.

Use an external agent

Once a Profile is available, you can choose it from the agent menus in Chat. A Profile that uses a Preset appears after setup finishes successfully.

To start a new conversation, open the dropdown beside the New chat button and select a Profile under External Agents.
Before sending the first message in an empty conversation, you can also use the Agent menu in the message box to choose a Profile. After you send the message, you cannot change the Agent for that conversation.

The Add agent entry in either menu opens Settings directly on the External Agents page. Send a message to begin the conversation. Huabu opens the selected Agent when needed and continues using it for that conversation. Type / in the message box to see any commands offered by that Agent.

A conversation keeps using the Profile it started with. Start a new conversation to use a different Agent or updated Profile settings.

Manage & troubleshoot

In Settings > External Agents, use to rename a Profile or update shared Preset configuration, and to remove it from future agent selectors. The launch command, selected agent, Preset, and working directory are fixed after creation; create a new Profile to change them. Existing chat threads keep the connection settings captured when they were created.

Symptom	What to check
An Agent is marked not installed	Install the indicated CLI or adapter, run it once in a terminal, and reopen the Add agent editor. Confirm that Huabu inherits the PATH containing the executable.
The Agent menu has no suitable installed agent	For a Profile without a Preset, use Custom command with the full ACP launch command. A Preset requires one of its supported agents and cannot use a custom command.
A Preset Profile is not available in Chat	Return to External Agents and check its status. Complete the required Preset configuration, then use Set up or Retry. When setup succeeds, the status badge disappears and the Profile becomes available in Chat.
Worker offline appears	Select Restart worker. If the error names a missing executable or path, correct the installation or Profile command first.
The agent starts but does not reply	Run the same agent command in a terminal and check authentication, provider access, first-run prompts, and ACP support. Also confirm that the working directory still exists and is accessible.