Skip to main content
Agent Profiles define which agent a new Agent Canvas conversation runs with. A profile can use the built-in OpenHands agent or an ACP agent such as Claude Code, Codex, or Gemini CLI. The active Agent Profile is the default agent for new conversations.

​
Agent Profiles vs LLM Profiles

Agent Profiles and LLM profiles control different layers: OpenHands Agent Profiles reference an LLM profile. ACP Agent Profiles use the external agent’s own model and authentication flow instead.

​
Manage Agent Profiles

Open Settings > Agent to manage the Agent Profile library. From this page, you can:
  • Create an OpenHands or ACP Agent Profile
  • Rename a profile
  • Edit profile settings
  • Set a profile as active
  • Delete profiles you no longer need
When you set a profile as active, new conversations use that profile by default.

​
Choose an Agent Profile for a Conversation

Before starting a conversation, you can open the + tools menu in the chat launcher and select Switch agent profile. Choose an Agent Profile to switch to that agent, and use it for the new conversation. The LLM Model selector always remains visible in the chat launcher and allows you to select from any available LLM that the current Agent Profile supports. Once a conversation is started with an Agent Profile you are unable to switch to a different Agent Profile during the conversation.

​
Scope an Agent Profile’s Secrets

When the connected Agent Server advertises the profile_secret_scope_v1 capability, the profile editor in Settings > Agent includes a secret scope picker for OpenHands and ACP profiles. Use it to control which saved secrets a profile can access:
  • All — the profile can access every saved secret (default for existing profiles).
  • None — the profile cannot access any saved secrets.
  • Selected — choose specific secret names from the list of saved secrets.
Secret references that no longer exist (for example, a secret that was deleted after being selected) are preserved in the profile rather than silently removed. This prevents an unrelated edit from widening or narrowing the profile’s secret access. Agent Server is the sole enforcement point for secret scoping. Canvas only stores the profile’s secret scope selection; it does not perform client-side secret filtering. On Agent Servers that do not advertise profile_secret_scope_v1, the picker is hidden and profiles remain unrestricted.

​
OpenHands Profiles

Use an OpenHands profile when you want Agent Canvas to run the built-in OpenHands agent. An OpenHands profile references an LLM profile, so model and credential changes are managed in Settings > LLM. Use this when you want Agent Canvas to own both the agent behavior and the model configuration.

​
Let the Agent Switch LLM Profiles

The OpenHands profile editor includes a “Let the agent switch LLM profiles” toggle. When enabled, the agent is given the SwitchLLMTool, which lets it switch between available LLM profiles during a conversation. When disabled, the tool is removed from the agent’s toolset. This toggle is version-gated: it appears only when the connected backend reports agent-server 1.31.0 or later. On older backends (for example, agent-server 1.29.0–1.30.x) the toggle is hidden.

​
Scope a Profile to Specific MCP Servers

An agent profile can be scoped to a subset of configured MCP servers using MCP server references (mcp_server_refs). When a profile includes MCP server references, only the tools from the referenced MCP servers are available to the agent in conversations that use that profile. This is useful when you have multiple MCP servers configured but want a particular profile to access only a subset — for example, restricting a profile to a documentation search server while excluding servers with broader tool access. To scope a profile:
  1. Open Settings > Agent and edit the agent profile.
  2. In the MCP server scoping section, select the MCP servers this profile should access.
  3. Save the profile.
When no MCP server references are set, the profile has access to all configured MCP servers. When references are set, only the selected servers’ tools are registered with the agent. See also Model Context Protocol for an overview of MCP support across OpenHands platforms.

​
ACP Profiles

Use an ACP profile when you want Agent Canvas to drive an external coding agent through the Agent Client Protocol. ACP profiles are useful for agents such as:
  • Claude Code
  • Codex
  • Gemini CLI
  • a custom ACP server
The external ACP agent owns its own model and tool behavior. Agent Server starts and manages the ACP process, while Agent Canvas renders the conversation and profile controls.

​
First-Time Setup

During first-time setup, the agent you choose becomes the initial active Agent Profile. If you choose OpenHands, the setup flow also configures the LLM profile that the Agent Profile uses. If you choose an ACP agent, the setup flow creates an ACP Agent Profile and uses that provider’s authentication path.