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. You can also choose a different profile from the chat launcher before starting a conversation.

​
Agent Profiles vs LLM Profiles

Agent Profiles and LLM profiles control different layers:
Profile TypeControlsWhere to Manage
Agent ProfileWhich agent runs the conversation and the agent-specific configurationSettings > Agent
LLM ProfileWhich LLM provider, model, and credentials an OpenHands agent usesSettings > LLM
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 a Profile for a Conversation

On the home screen, use the agent profile picker in the chat launcher to choose the profile for the next conversation. This selection affects the conversation you are about to start. Existing conversations keep the agent profile they were launched with.

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

​
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 Canvas starts the agent process and renders the conversation.

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