Bring Your Own Agent Without Losing the Boundary

OpenHands Agent Canvas can place an external coding agent inside the same conversation surface as the built-in OpenHands agent, but it does not erase the difference between them. This chapter follows what changes when the selected agent is an ACP process: who launches it, where its model and tools live, how a local login differs from a container credential, and how skills, MCP servers, and runtime topology reach the conversation. The practical judgment is whether “use any agent” preserves the boundaries that make the chosen backend understandable and controllable.

ACP changes who owns the model-powered process

The Agent Client Protocol, or ACP, is a standard way to communicate with coding agents over JSON-RPC on standard input and output. That description is more important than the provider names that appear in a menu. In a direct OpenHands path, the Agent Server assembles and runs the OpenHands agent through its own runtime contract. In an ACP path, the Agent Server starts another program as a subprocess and relays turns to it. The external program manages its own model interaction, tools, and execution behavior.

Canvas remains the place where the user chooses an agent, supplies a model preference, and starts a conversation. The Agent Server remains the authority that owns the subprocess and its credentials. The provider CLI becomes the authority for the details of its own agent loop. This creates a chain of responsibility rather than a single “agent” box. Canvas can show a Claude Code, Codex, Gemini CLI, or custom ACP choice, but it cannot make their tool semantics, authentication, or model availability identical.

That separation explains why the Agent settings screen stores an agent kind, a selected ACP server or preset, a launch command, and a model rather than an ordinary LLM configuration alone. A preset can fill in a provider’s normal command and suggested model. A custom server can use another stdio command and the model identifier its implementation expects. Editing the command can change which process is launched without requiring Canvas to understand the internals of that process.

The conversation path looks like this:

sequenceDiagram participant U as Developer participant C as Canvas participant S as Agent Server participant K as Secret store participant P as ACP process participant M as Model provider U->>C: Choose ACP agent and model C->>S: Save agent settings C->>S: Start conversation with optional secret references opt Saved secrets are referenced S->>K: Resolve LookupSecret values K-->>S: Credential material end alt Local provider login S->>P: Spawn CLI using existing login else Container or API-key path S->>P: Spawn CLI with env or file credential end P->>M: Model and tool requests P-->>S: JSON-RPC conversation updates S-->>C: Runtime events C-->>U: Rendered response and controls

The important arrow is from Agent Server to ACP process. Canvas does not call the provider’s model directly and then imitate an agent conversation. It sends conversation intent to the backend, and the backend launches the provider process in the environment where that process is supposed to run.