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.
The special rules for a profile named default apply to local backends only. On an OpenHands Cloud or Enterprise backend, an organization profile named default behaves like any other profile.

​
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.

​
Profile-Owned Settings

Every local launch sends an agent_profile_id, including the built-in default profile. default is an ordinary profile that launches from its own stored settings rather than from the global settings pages. The settings a profile shares with a global page have one owner each, so editing either side changes both:
  • Skills — On a local backend with an OpenHands default, the Skills page reads and writes default’s skill selection. The profile editor’s Skills section lists the skills a launch can load, taken from the agent-server’s skill catalog, and labels each entry Catalog or Your skill.
  • MCP servers — An OpenHands default loads every MCP server switched on in MCP Servers. Switching a server on or off in default’s editor applies to every profile.
  • LLM — default always launches on the active LLM profile.
  • Secrets — An OpenHands default always has every saved secret, and its editor has no secret picker. An ACP default keeps its own secret and MCP scopes.
Small settings — condenser, verification, Model Router, tools, parallel tool calls, system prompt suffix, and persona — live only in profiles. A new profile copies them from default. A profile stores a section only once you edit it, and a profile always carries both condenser and verification fields. The critic API key stays global and never reaches a profile. default cannot be renamed or deleted. The server reseeds a deleted default, which would reset the values it shares with the global pages.

​
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.

​
Set a Profile’s System Prompt

The OpenHands profile editor includes a System prompt section. Choose one of three modes:
  • OpenHands default — Uses the built-in OpenHands instructions for coding, security, and tool use.
  • Default + your instructions — Adds your instructions after the built-in OpenHands instructions, which stay in place.
  • Custom persona — Replaces OpenHands’ built-in persona and coding workflow. Memory, security and tool guidance, skills, repository instructions, and runtime context are still included.
The default profile uses the OpenHands system prompt until you change it. Create a named profile to keep a different prompt separate from default.

​
Choose a Profile’s Tools

A named OpenHands profile can choose its tools from the connected server’s catalog:
  • Standard tools — The agent gets the tools the server considers standard. The list follows the server, so it can change when the server is upgraded.
  • Choose tools — The agent gets only the tools you select. Removing a tool removes the ability, not just the instruction to avoid it.
A new profile starts from default’s tool selection. If the server’s tool catalog cannot be loaded, the editor shows a retry action instead of the tool list.

​
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.