diff --git a/docs.json b/docs.json index b5b7db02..f7bc4965 100644 --- a/docs.json +++ b/docs.json @@ -205,6 +205,9 @@ "openhands/usage/agent-canvas/overview", "openhands/usage/agent-canvas/setup", "openhands/usage/agent-canvas/first-time-setup", + "openhands/usage/agent-canvas/conversations", + "openhands/usage/agent-canvas/agent-profiles", + "openhands/usage/agent-canvas/plugins", { "group": "Pre-built Automations", "pages": [ diff --git a/openhands/usage/agent-canvas/agent-profiles.mdx b/openhands/usage/agent-canvas/agent-profiles.mdx new file mode 100644 index 00000000..0c66cee7 --- /dev/null +++ b/openhands/usage/agent-canvas/agent-profiles.mdx @@ -0,0 +1,70 @@ +--- +title: Agent Profiles +description: Manage reusable agent configurations for Agent Canvas conversations. +--- + +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 Type | Controls | Where to Manage | +|--------------|----------|-----------------| +| **Agent Profile** | Which agent runs the conversation and the agent-specific configuration | `Settings > Agent` | +| **LLM Profile** | Which LLM provider, model, and credentials an OpenHands agent uses | `Settings > 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. + +## Related Guides + +- [First Time Setup](/openhands/usage/agent-canvas/first-time-setup) +- [ACP Agents](/openhands/usage/agent-canvas/acp-agents) +- [LLM Profiles and Model Configuration](/openhands/usage/agent-canvas/llm-profiles) diff --git a/openhands/usage/agent-canvas/conversations.mdx b/openhands/usage/agent-canvas/conversations.mdx new file mode 100644 index 00000000..7c8fd093 --- /dev/null +++ b/openhands/usage/agent-canvas/conversations.mdx @@ -0,0 +1,90 @@ +--- +title: Conversations +description: Work with Agent Canvas conversations, including branching from previous messages. +--- + +A conversation is a single agent session on the active backend. It has its own message history, tool calls, file changes, selected agent profile, and conversation-specific plugins. + +## Branch From a Message + +Use `Branch from here` on a message when you want to explore a different path without changing the original conversation. + +Branching creates a new conversation from the selected point in the current conversation. The original conversation remains available in the sidebar. + + + Conversation branching is available on local agent-server backends that support conversation forks. + + +## Branching User Messages + +Branching from one of your own messages works like edit-and-resend: + +1. Hover over the message. +2. Select `Branch from here`. +3. Agent Canvas opens a new branched conversation. +4. The selected message appears in the composer so you can edit it before sending. + +The new branch starts from the parent of that message. This lets you rewrite the prompt and continue from the earlier state. + +## Branching Assistant Messages + +Branching from an assistant message creates a new conversation that includes history through that assistant response. + +Use this when the agent reached a useful point and you want to try a different next step without changing the original thread. + +## What Branching Preserves + +The branch keeps the relevant conversation history, agent configuration, workspace context, and backend-managed state needed to continue from the branch point. + +The branch is independent after creation: + +- messages you send in the branch do not modify the original conversation +- the original conversation stays in the sidebar +- branches can be branched again +- the branch gets its own conversation title + +## Branching vs Starting Fresh + +Start a fresh conversation when you want no prior context. + +Branch a conversation when you want the agent to remember what happened up to a specific message, but you want to test a different instruction, correction, or follow-up. + +## Run a Goal + +Use the `/goal` command when you want the agent to keep working until a specific objective is complete or the goal reaches its iteration limit. + +```text +/goal [--max N] +``` + +For example: + +```text +/goal --max 3 add unit tests for the parser and verify they pass +``` + +When you start a goal, Agent Canvas runs the agent and uses a judge LLM to check whether the objective is complete after each round. If the judge finds missing work, Agent Canvas sends that feedback back to the agent and continues until the goal is complete or the maximum number of rounds is reached. + +While a goal is running, Agent Canvas shows a status banner with the objective, current round, status, judge score, and any missing work. When the goal finishes, the final status appears inline in the conversation history. + +Goal statuses include: + +| Status | Meaning | +|--------|---------| +| `running` | The goal loop is active | +| `complete` | The judge confirmed the objective is done | +| `capped` | The goal reached its maximum number of rounds | +| `interrupted` | A normal user message interrupted the active goal | + +Sending a normal message while a goal is running interrupts the goal and gives control back to you. + + + The `/goal` command requires a backend that supports conversation goal routes. It uses both the agent LLM and a judge LLM, so goal runs may make additional model calls beyond the agent's normal work. + + +## Related Guides + +- [Fork a Conversation](/sdk/guides/convo-fork) +- [Goal Completion Loop](/sdk/guides/convo-goal) +- [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles) +- [Plugins in Agent Canvas](/openhands/usage/agent-canvas/plugins) diff --git a/openhands/usage/agent-canvas/customize-and-settings.mdx b/openhands/usage/agent-canvas/customize-and-settings.mdx index 26808f42..2ab5c56a 100644 --- a/openhands/usage/agent-canvas/customize-and-settings.mdx +++ b/openhands/usage/agent-canvas/customize-and-settings.mdx @@ -27,7 +27,7 @@ The `Settings` area currently includes the following sections: | Section | Purpose | |---------|---------| -| `Agent` | Agent behavior and agent-specific capabilities | +| `Agent` | Agent Profile library and agent-specific capabilities | | `LLM` | Provider, model, API key, and profile configuration | | `Condenser` | Context compression and summarization behavior | | `Verification` | Approval, critic evaluation, and verification-related behavior | @@ -36,6 +36,8 @@ The `Settings` area currently includes the following sections: On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles. +Use `Settings > Agent` to choose the active Agent Profile for new conversations. OpenHands profiles reference LLM profiles from `Settings > LLM`; ACP profiles use the external agent's own model configuration. + ## Configuration Is Per Backend Both Customize and Settings are tied to the **active backend**. That means: @@ -56,5 +58,7 @@ You might use this split like this: ## Related Guides - [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) +- [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles) +- [Plugins in Agent Canvas](/openhands/usage/agent-canvas/plugins) - [Configure the Critic](/openhands/usage/agent-canvas/critic) - [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations) diff --git a/openhands/usage/agent-canvas/first-time-setup.mdx b/openhands/usage/agent-canvas/first-time-setup.mdx index 92221e6b..ac060555 100644 --- a/openhands/usage/agent-canvas/first-time-setup.mdx +++ b/openhands/usage/agent-canvas/first-time-setup.mdx @@ -18,7 +18,7 @@ Agent Canvas uses the **Agent-Client Protocol (ACP)** to communicate with agents Choosing a third-party agent lets you interact with it through the Agent Canvas interface and bring your existing subscriptions from those providers. -You can change your agent at any time from `Settings`. +Your choice creates the initial active [Agent Profile](/openhands/usage/agent-canvas/agent-profiles). You can change your active profile or create additional profiles later from `Settings > Agent`. ## Step 2: Check Your Backend @@ -51,6 +51,8 @@ Available options: The setup screen defaults to `OpenHands` as the provider and pre-selects a recommended model. Switch the `LLM Provider` dropdown to choose a different provider. +For OpenHands Agent Profiles, this LLM setup becomes the model profile the agent uses. ACP agents such as Claude Code, Codex, and Gemini CLI use their own authentication and model configuration. + ## Step 4: Start From a Proven Workflow ![Agent Canvas first-time setup — Say hello screen showing pre-built workflow templates including GitHub PR review copilot, GitHub repository monitor, and Slack standup digest](/openhands/static/img/agent-canvas-setup-step-4.png) diff --git a/openhands/usage/agent-canvas/llm-profiles.mdx b/openhands/usage/agent-canvas/llm-profiles.mdx index d5665111..e995e7e0 100644 --- a/openhands/usage/agent-canvas/llm-profiles.mdx +++ b/openhands/usage/agent-canvas/llm-profiles.mdx @@ -22,6 +22,8 @@ LLM profiles are useful when you want different model setups for different tasks - a stronger profile for planning or review - a local model profile for offline experiments +LLM profiles are separate from [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles). Agent Profiles choose which agent runs a new conversation. OpenHands Agent Profiles reference an LLM profile to decide which model configuration that agent uses. + ## Switching Profiles in a Conversation You can switch profiles from the chat input with the `/model` command: @@ -39,11 +41,13 @@ Agent Canvas also shows model-switch events in the conversation timeline so you 1. Configure a default profile in `Settings > LLM`. 2. Create additional profiles for specific tasks or cost levels. -3. Start a conversation. -4. Use `/model` when you want to switch profiles without leaving the chat. +3. Open `Settings > Agent` and choose which LLM profile an OpenHands Agent Profile should use. +4. Start a conversation. +5. Use `/model` when you want to switch profiles without leaving the chat. ## Related Guides - [Setup](/openhands/usage/agent-canvas/setup) - [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings) +- [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles) - [LLM Settings](/openhands/usage/settings/llm-settings) diff --git a/openhands/usage/agent-canvas/plugins.mdx b/openhands/usage/agent-canvas/plugins.mdx new file mode 100644 index 00000000..b070889f --- /dev/null +++ b/openhands/usage/agent-canvas/plugins.mdx @@ -0,0 +1,77 @@ +--- +title: Plugins in Agent Canvas +description: Browse, install, attach, and inspect plugins in Agent Canvas. +--- + +Plugins bundle related agent capabilities, such as skills, MCP servers, hooks, commands, and agent definitions. Agent Canvas gives local backends a UI for browsing the plugin catalog, installing plugins, enabling or disabling installed plugins, and attaching plugins when you start a conversation. + + + The Plugins management page is available for local backends. Cloud backends may show an empty plugin catalog or disable plugin management actions until plugin management is available for that backend. + + +## Open the Plugins Area + +Open `Plugins` from the sidebar to manage plugins for the active backend. + +From the Plugins page, you can: + +- Search the plugin catalog +- Inspect plugin details +- Install a plugin from the catalog or source +- Enable or disable installed plugins +- Uninstall plugins that are managed by Agent Canvas +- Confirm locally discovered plugins + +Plugin management is backend-scoped. Switching backends changes which installed and local plugins you see. + +## Installed and Local Plugins + +Agent Canvas shows plugin status in the Plugins page: + +| Status | Meaning | +|--------|---------| +| `Installed` | The plugin is managed by Agent Canvas and can be enabled, disabled, or uninstalled | +| `Available` | The plugin is visible in the catalog but not installed | +| `Local` | The plugin was discovered from a local plugin directory and is shown as read-only | + +Local plugins are discovered from user-level plugin directories such as `~/.agents/plugins` and `~/.openhands/plugins`. They can load into conversations, but Agent Canvas does not manage their lifecycle from the UI. + + + Local plugins are read-only in the Plugins page. To change or remove a local plugin, edit the files in the local plugin directory. + + +## Enable or Disable Installed Plugins + +Enabled installed plugins are automatically available to new conversations on that backend. Disabled plugins remain installed, but they are not loaded into new conversations. + +Use this when you want to keep a plugin available without making it part of every new conversation. + +## Attach Plugins to a New Conversation + +When you start a new conversation, use the `Plugins` picker in the chat launcher to attach catalog plugins explicitly. + +Attached plugins are opt-in for that conversation. If you start another conversation without selecting plugins, Agent Canvas does not attach any conversation-specific plugins. + +Installed and enabled plugins may still load automatically for new conversations, depending on the active backend configuration. + +## View Attached Plugins During a Conversation + +When a conversation has explicitly attached plugins, open the conversation tools menu and select `Show Plugins` to see them. + +This view lists plugins attached when the conversation was created. It is display-only and does not include every ambient or installed plugin that might also be available to the backend. + +## Trust and Backend Scope + +Plugins can add instructions, tools, hooks, and external integrations. Install plugins only from sources you trust, and review what a plugin contains before enabling it. + +Because plugins are managed by the active backend: + +- A local backend can discover local plugin directories on that machine +- A remote backend uses its own plugin state, not your laptop's plugin directories +- Switching backends can change which plugins are installed, enabled, or local + +## Related Guides + +- [Plugins](/overview/plugins) +- [SDK Plugins](/sdk/guides/plugins) +- [Connect and Manage Backends](/openhands/usage/agent-canvas/backends) diff --git a/openhands/usage/agent-canvas/prebuilt-automations.mdx b/openhands/usage/agent-canvas/prebuilt-automations.mdx index 0f9c2b98..92a06923 100644 --- a/openhands/usage/agent-canvas/prebuilt-automations.mdx +++ b/openhands/usage/agent-canvas/prebuilt-automations.mdx @@ -24,6 +24,7 @@ In the `Automate` view, you can: - Browse existing automations - Inspect automation configuration and activity - Enable or disable automations +- Edit an automation's LLM profile for future runs - Work with recommended automation flows ## How Creation Flows Usually Start @@ -35,6 +36,12 @@ In practice, new automation setup often starts in one of two ways: - From a conversation, where you ask OpenHands to create an automation for you - From a recommended automation flow in the `Automations` view -Visit the Automations Docs have a more [detailed guide on creating automations](/openhands/usage/automations/creating-automations). +For a detailed walkthrough, see [Creating Automations](/openhands/usage/automations/creating-automations). Automations run against the active backend. Use [Manage Backends](/openhands/usage/agent-canvas/backends) to see and switch which backend your automations run on. + +## Edit an Automation's LLM Profile + +Open an automation, select `Edit`, and use the `LLM profile` dropdown to change which saved profile future runs use. If an automation already has a profile, the edit dialog pre-selects it. + +Changing the LLM profile affects future automation runs. It does not rewrite previous run history.