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.

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