External Agents

Bring your existing agent harnesses into a shared visual workspace, without configuring a built-in model provider.

What is an external agent?

Huabu is a visual interface for the agents you already use. An agent harness is the environment that runs your agent and provides its model access, tools, and permissions. Connect ACP-compatible agents on a connected device and choose them through saved Profiles. Huabu supplies the Space context, conversation interface, and change review. Authentication and usage charges remain with the agent or its provider. Built-In Pi is optional, not a prerequisite.

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 device where it will run. For the usual local desktop setup, this is your own computer. For another device, open Settings > Agent > Connected devices > Add device and follow the Agentlet connection instructions.

Install an ACP-compatible agent. Huabu automatically detects these ten ACP-capable agent commands or adapters after installation: GitHub Copilot, Claude Agent, Gemini, Codex, Qwen Code, Kimi Code, OpenCode, Cursor, CodeBuddy, and Hermes Agent. 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 the connected device can find the agent. The agent command must be on the PATH inherited by its Agentlet process. Restart the local desktop app or reconnect the device after installing the agent or changing PATH. Claude and Codex require their ACP adapters, not only the native CLI. 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 agent harness on a connected device, with a launch configuration and working directory. Supported agents discovered when a device connects receive Profiles automatically; you do not need to create one manually to start using them. Discovery does not install agents or sign in for you.

To create another Profile, open Settings () > Agent > External agents, select Add agent, and complete these fields:

Field	What to choose
Device	Choose the connected device where the agent will run. Agent commands and working-directory paths belong to that device.
Agent	Choose a supported installed harness, or Custom command for another ACP-compatible launch command. Missing agents or adapters must be installed on the selected device first.
Auto-approve all tool calls	Available only for harnesses that support it. Newly discovered automatic Profiles enable it when supported; review this setting because it bypasses tool confirmations.
Working directory	An absolute folder path on the selected device. Automatic Profiles receive a default workspace; manually created Profiles need a working directory you choose.
Display name	A label that identifies this Profile in Settings and Agent selectors.
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.

Save the Profile, then select it when starting a conversation. Use Custom command when you need an absolute executable path, extra flags, or an ACP agent Huabu does not detect. Enter the complete command documented by that agent.

Utility tasks

A connected external Profile can also handle Huabu-owned background tasks such as titles, summaries, keywords, and image labels. Review the selection under Settings > Agent > Utility tasks. If no Utility Agent configuration exists, Huabu selects an available external Profile automatically. Existing selections are preserved.

Utility tasks do not silently fall back to Built-In Pi. The selected device and agent must remain available. Image tasks require image support, and automatic Huabu Memory curation still requires a Built-In Pi Utility Agent. See Models & Capabilities for optional services and other limits.

Use an external agent

Once its device is connected, choose the Profile from the agent menus in Chat. You do not need to configure a separate Huabu Chat Model.

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 Agent 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 > Agent > External agents, use to edit a Profile, and to remove it from future agent selectors. You can update its name, icon, working directory, and supported launch options. A Custom command Profile also allows command edits. The device and harness identity are fixed; create another Profile to change them. Edits apply to conversations that have not started, not already-running sessions. Deleting a Profile does not delete its working directory, and later discovery can recreate an automatic default.

Symptom	What to check
An Agent is marked not installed	Install the indicated CLI or ACP adapter on the selected device, complete sign-in, and reconnect it. Confirm that Agentlet inherits the PATH containing the executable.
The Agent menu has no suitable installed agent	Check Connected devices, then install a supported harness or use Custom command with the full ACP launch command on that device.
An existing Profile is not available in Chat	Confirm that its device is connected. Offline Profiles remain editable in Settings but cannot be selected for new work.
Background tasks fail after changing devices	Check the selected Profile under Utility tasks. Huabu preserves that selection when a device disconnects or a Profile is deleted; choose another available Profile explicitly.
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.