From 8f1d211c23e0d62209cbbaf2bbf661ec7a866fa5 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 6 Oct 2026 01:08:51 +0000 Subject: [PATCH 1/2] docs: update documentation for OpenHands v1.25.0 Add a v1.25.0 release-notes page and document the user-facing Agent Canvas changes in their feature pages: Model Router settings, bulk-adding provider models as LLM profiles, agent-profile system prompt and tool selection, voice input and workspace file discovery in conversations, the Canvas App Update action and manifest icon, the Automations creator filter, and automation templates on cloud backends. Co-authored-by: openhands --- docs.json | 1 + .../usage/agent-canvas/agent-profiles.mdx | 19 ++++++++++ .../usage/agent-canvas/canvas-extensions.mdx | 11 +++++- .../usage/agent-canvas/conversations.mdx | 32 +++++++++++++++++ .../agent-canvas/customize-and-settings.mdx | 2 +- openhands/usage/agent-canvas/llm-profiles.mdx | 16 +++++++++ .../agent-canvas/managing-automations.mdx | 10 ++++++ .../agent-canvas/model-configuration.mdx | 19 ++++++++++ .../agent-canvas/prebuilt-automations.mdx | 2 +- .../agent-canvas/release-notes/v1.25.0.mdx | 36 +++++++++++++++++++ 10 files changed, 145 insertions(+), 3 deletions(-) create mode 100644 openhands/usage/agent-canvas/release-notes/v1.25.0.mdx diff --git a/docs.json b/docs.json index 560ae49e0..64b8adbb5 100644 --- a/docs.json +++ b/docs.json @@ -323,6 +323,7 @@ { "group": "Release Notes", "pages": [ + "openhands/usage/agent-canvas/release-notes/v1.25.0", "openhands/usage/agent-canvas/release-notes/v1.24.0", "openhands/usage/agent-canvas/release-notes/v1.23.0", "openhands/usage/agent-canvas/release-notes/v1.22.0", diff --git a/openhands/usage/agent-canvas/agent-profiles.mdx b/openhands/usage/agent-canvas/agent-profiles.mdx index 6f421d491..f10160990 100644 --- a/openhands/usage/agent-canvas/agent-profiles.mdx +++ b/openhands/usage/agent-canvas/agent-profiles.mdx @@ -80,6 +80,25 @@ When no MCP server references are set, the profile has access to all configured See also [Model Context Protocol](/overview/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 always uses the OpenHands system prompt. Create a named profile to customize it. + +### 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. + +The default profile always launches with the global tool set. Create a named profile to choose its tools. 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. diff --git a/openhands/usage/agent-canvas/canvas-extensions.mdx b/openhands/usage/agent-canvas/canvas-extensions.mdx index fddb97455..0703a3d09 100644 --- a/openhands/usage/agent-canvas/canvas-extensions.mdx +++ b/openhands/usage/agent-canvas/canvas-extensions.mdx @@ -75,6 +75,14 @@ Enabling an app runs its JavaScript in the same browser context as Agent Canvas. Only enable apps whose code and resolved revision you trust. An enabled app has the browser authority available to Agent Canvas and can use an authenticated helper to call the active Agent Server. +### Update an App + +Apps installed from a Git repository or a backend-local path can be updated in place. Use the app's `Update` action to re-resolve its source and copy the new files over the installed version, without uninstalling and reinstalling it. This picks up changes even when the app's manifest version did not change. If the copy fails, the previously installed version keeps working. + +### App Icons + +An app can declare an `icon` in its manifest. When present, Agent Canvas loads the SVG from that path and shows it on the app's sidebar item and card. + ## Build an App An app is a directory containing: @@ -94,6 +102,7 @@ The current package format uses manifest schema `1` and host API `1`. "display_name": "Example dashboard", "version": "0.1.0", "description": "A project dashboard for Agent Canvas.", + "icon": "icon.svg", "entrypoint": "extension.js", "contributes": { "pages": [ @@ -110,7 +119,7 @@ The current package format uses manifest schema `1` and host API `1`. Use lowercase letters, numbers, and hyphens for app names and page IDs. Page paths must start with `/`, and every page ID and path must be unique within the app. -The `entrypoint` must stay inside the app root. Bundle dependencies, CSS, and required assets into one browser ESM file; unresolved package imports and external runtime chunks cannot be loaded. +The `entrypoint` must stay inside the app root. Bundle dependencies, CSS, and required assets into one browser ESM file; unresolved package imports and external runtime chunks cannot be loaded. If you declare an `icon`, it must also stay inside the app root; Agent Canvas serves it from `GET /api/canvas-extensions/installed/{name}/icon`. ### Register the Page diff --git a/openhands/usage/agent-canvas/conversations.mdx b/openhands/usage/agent-canvas/conversations.mdx index 59bf140a8..6660cd931 100644 --- a/openhands/usage/agent-canvas/conversations.mdx +++ b/openhands/usage/agent-canvas/conversations.mdx @@ -47,6 +47,24 @@ When an agent creates a Markdown file, Agent Canvas renders it inline as a heigh When you upload an image as part of a message or an image is produced in a conversation, Agent Canvas displays it as a thumbnail. Click the thumbnail to open the image full size in a lightbox overlay. Dismiss the lightbox by pressing Escape, clicking the close button, or clicking the backdrop. +## Voice Input + +Agent Canvas can add an optional microphone button to the chat input so you can dictate messages. Select the microphone to start dictation and select it again to stop; the transcript is added to the composer. + +By default, the microphone button uses your browser's speech recognition. To use your own transcription service instead, such as a local Whisper server, open `Settings > Application > Voice input` and enter an OpenAI-compatible endpoint: + +| Field | Purpose | +|-------|---------| +| `Base URL` | The transcription endpoint, for example `https://api.openai.com/v1` | +| `API key` | The key for that endpoint | +| `Model` | The transcription model; defaults to `whisper-1` | + +These voice input settings are stored in this browser only. The API key is kept in session storage so it is not persisted at rest. + + + If dictation fails, Agent Canvas reports that dictation failed and asks you to check microphone access and your voice input settings. Grant the browser microphone permission and confirm the endpoint details before retrying. + + ## Conversation Overview Panel The conversation overview panel displays project context for the active conversation, including workspace information, git state, and loaded resources such as skills, MCP servers, and automations. @@ -72,6 +90,20 @@ Above the file tree, the active workspace path is displayed with a copy button. The workspace path row is hidden when the conversation has no working directory. +### File Discovery + +The Files panel discovers files per workspace. Open the file discovery settings to control what the tree includes: + +| Setting | Purpose | +|---------|---------| +| `Excluded directories` | One pattern per line. Names match anywhere; paths are relative to the workspace. Use `*/bin` to exclude nested `bin` directories while keeping the root `bin`. | +| `Include symbolic links to files` | Include symlinks that point to files. | +| `Maximum files (0 for unlimited)` | Cap the number of files the tree loads. Set to `0` to remove the cap. | + +Select `Restore defaults` to reset the settings. File discovery settings apply to this workspace on this backend, including other conversations that use the same workspace. + +When the number of discovered files exceeds the configured maximum, the tree is truncated and shows a finite limit notice: `Showing the first files. This tree is incomplete. Adjust File discovery to see more.` Raise the maximum or narrow the exclusions to load more of the tree. + ## Context Window Usage and Manual Compaction Agent Canvas shows a context-window meter in the composer that visualizes how much of the model's available context is in use. The meter fills as the conversation grows. diff --git a/openhands/usage/agent-canvas/customize-and-settings.mdx b/openhands/usage/agent-canvas/customize-and-settings.mdx index 2e3ea4e23..54b2f8cd2 100644 --- a/openhands/usage/agent-canvas/customize-and-settings.mdx +++ b/openhands/usage/agent-canvas/customize-and-settings.mdx @@ -53,7 +53,7 @@ The `Settings` area currently includes the following sections: | Section | Purpose | |---------|---------| | `Agent` | Agent Profile library and agent-specific capabilities | -| `LLM` | Provider, model, API key, profile configuration, and provider connections | +| `LLM` | Provider, model, API key, profile configuration, provider connections, and Model Router | | `Condenser` | Context compression and summarization behavior | | `Verification` | Approval, critic evaluation, and verification-related behavior | | `Application` | UI-level preferences and app behavior | diff --git a/openhands/usage/agent-canvas/llm-profiles.mdx b/openhands/usage/agent-canvas/llm-profiles.mdx index 22259f27b..46d5c59e2 100644 --- a/openhands/usage/agent-canvas/llm-profiles.mdx +++ b/openhands/usage/agent-canvas/llm-profiles.mdx @@ -100,6 +100,22 @@ Linked profiles are grouped under their Provider Connection name in the profile Edit a Provider Connection to rename it, rotate its API key, or change its base URL. The update applies to every linked profile. Before deleting a connection, re-link or change every profile that uses it; Agent Canvas prevents deleting a connection while profiles still reference it. +### Bulk Add Models as Profiles + +When you want several models from one provider as saved profiles, use the bulk-add flow instead of creating each profile separately. + +1. Open `Settings > LLM` and select the add action to open `Add models as profiles`. +2. Choose a provider from the searchable provider list. +3. Select the models to add, or use `Select all`. +4. Optionally select a `Provider connection` to link the new profiles to. Linked profiles inherit that connection's key; with `No connection (keyless)` selected, the profiles are created without credentials and need a key added later. +5. Confirm to create the profiles. + +The same bulk-add action is available per provider connection. Use the connection's `Bulk add` action to add every selected model directly under that connection, so each new profile inherits the connection's credentials without repeating the key. + + +Provider Connections are available on local agent-server backends only. On OpenHands Cloud, bulk-add creates keyless profiles unless you add a key to each one afterwards. + + ## Working with LLM Profiles LLM profiles are useful when you want different model setups for different tasks, such as: diff --git a/openhands/usage/agent-canvas/managing-automations.mdx b/openhands/usage/agent-canvas/managing-automations.mdx index f2efa3d6b..bab7fedf6 100644 --- a/openhands/usage/agent-canvas/managing-automations.mdx +++ b/openhands/usage/agent-canvas/managing-automations.mdx @@ -21,6 +21,16 @@ Click an automation to open its detail view. The detail view shows: - LLM profile used for runs - Recent run history and status +### Filter by Creator + +On OpenHands Cloud, the Automate view includes a **Filter by creator** control with `Anyone`, `Me`, and `Others` options. + +- `Anyone` shows every automation you can see. +- `Me` shows only automations you created. +- `Others` shows automations created by other members. + +The filter is applied by the backend, so it returns matching automations even when they are not on the first page of results. + ### Run Statuses A run can be `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, or `SKIPPED`. A `SKIPPED` run can occur when the backend reaches its concurrency limit. Future backend statuses appear as a neutral status badge so they do not prevent you from viewing the automation. diff --git a/openhands/usage/agent-canvas/model-configuration.mdx b/openhands/usage/agent-canvas/model-configuration.mdx index 9bfb975a9..8a28a301e 100644 --- a/openhands/usage/agent-canvas/model-configuration.mdx +++ b/openhands/usage/agent-canvas/model-configuration.mdx @@ -37,6 +37,25 @@ When a profile uses a Provider Connection, its API key and base URL come from th Provider Connections are available on local agent-server backends. The panel is hidden when using an OpenHands Cloud backend. +## Model Router + +A **Model Router** is a profile that routes each task to the right LLM profile instead of pinning a conversation to a single model. Manage routers from the `Model Router` section of `Settings > LLM`. + +To create a router: + +1. Open `Settings > LLM` and select `Model Router`. +2. Select `Add Model Router`. +3. Choose a template: `Add OpenHands Router Pro`, `Add OpenHands Router Flash`, or `Custom`. Router templates let you keep `Don't create profiles` so the template does not add LLM profiles of its own. +4. Review the generated configuration, then save the router. + +The Model Router settings include a **Run on first message** toggle. When enabled, the first message of every new conversation is routed through the active Model Router before the agent proceeds. The toggle is off by default; Agent Canvas turns it on automatically when you create the first router. Its state is saved with the backend settings, so it persists across reloads. + +Model routing requires a backend that supports it. If the connected backend does not, the `Model Router` section reports that the backend does not support model routing yet and asks you to update the agent server. + + + Model Router is separate from the [LLM profiles](/openhands/usage/agent-canvas/llm-profiles) it routes to. Each router chooses among existing profiles rather than replacing them. + + ## Direct Provider or OpenHands Profile Use the `Basic` tab when you have an API key from Anthropic, OpenAI, Google, OpenHands, or another provider in the selector. diff --git a/openhands/usage/agent-canvas/prebuilt-automations.mdx b/openhands/usage/agent-canvas/prebuilt-automations.mdx index 321380d0f..2bef231c1 100644 --- a/openhands/usage/agent-canvas/prebuilt-automations.mdx +++ b/openhands/usage/agent-canvas/prebuilt-automations.mdx @@ -41,7 +41,7 @@ For recommended automations that support a direct form setup, Agent Canvas check Some catalog entries ship a **script bundle** — a packaged set of files that install as a deterministic automation — rather than a prompt-based preset. Script-bundle entries run their own logic for tasks like polling, deduplication, and fixed API calls, using the agent only for the parts that genuinely require judgment. When a catalog entry supports a bundle install, the setup form handles packaging and upload automatically; you just fill in the required fields. -Catalog entries that accept repositories can also collect multiple repositories in a single field, so one automation can monitor several repos at once. +Catalog entries that accept repositories can also collect multiple repositories in a single field, so one automation can monitor several repos at once. Automation templates appear on cloud backends as well as local backends. Where the built-in Git integration is offered, Agent Canvas presents it before the issue-to-PR templates. For a detailed walkthrough, see [Creating Automations](/openhands/usage/automations/creating-automations). diff --git a/openhands/usage/agent-canvas/release-notes/v1.25.0.mdx b/openhands/usage/agent-canvas/release-notes/v1.25.0.mdx new file mode 100644 index 000000000..e77b6d8d2 --- /dev/null +++ b/openhands/usage/agent-canvas/release-notes/v1.25.0.mdx @@ -0,0 +1,36 @@ +--- +title: Agent Canvas 1.25.0 +description: Release notes for Agent Canvas version 1.25.0 +--- + +# Agent Canvas 1.25.0 + +Released October 6, 2026. + +[View the full release on GitHub](https://github.com/OpenHands/OpenHands/releases/tag/v1.25.0). + +## Highlights + +- **Model Router settings** — Configure routers that route each task to the right LLM profile, with a **Run on first message** toggle that routes the first message of every new conversation. See [Configure a Model](/openhands/usage/agent-canvas/model-configuration#model-router). +- **Bulk-add provider models as LLM profiles** — Create several LLM profiles at once from a provider picker, optionally binding them to a provider connection so they inherit its credentials. See [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles#bulk-add-models-as-profiles). +- **Agent profile persona and instructions** — Give a profile its own system prompt, choosing between the OpenHands default, added instructions, or a custom persona. See [Agent Profiles](/openhands/usage/agent-canvas/agent-profiles#set-a-profiles-system-prompt). +- **Voice input** — An optional microphone button in the chat input, backed by browser speech recognition or an OpenAI-compatible transcription endpoint. See [Conversations](/openhands/usage/agent-canvas/conversations#voice-input). +- **Workspace file discovery** — Configure which files the Files panel discovers per workspace, including excluded directories, included symlinks, and a file-count limit. See [Conversations](/openhands/usage/agent-canvas/conversations#file-discovery). +- **Update installed Apps** — Update an app installed from a local path or Git in place, without uninstalling and reinstalling it. See [Apps (Beta)](/openhands/usage/agent-canvas/canvas-extensions). +- **Automations dashboard filter by creator** — Filter the Automations dashboard by anyone, you, or others. See [Managing automations](/openhands/usage/agent-canvas/managing-automations). + +## Fixes + +- Agent profiles pick their tools from the server's catalog, so the available tool list follows the connected server. +- Automation templates are offered on cloud backends, and the built-in integration is offered before issue-to-PR templates. +- Conversation title generation uses the running agent profile's LLM. +- Focused settings pages keep their keyboard and viewport behavior on narrow screens. + +## Maintenance + +- Pinned agent-server and SDK to 1.53.0, with Extensions and Automation dependency bumps. + +## Full Changelog + +- [GitHub release notes](https://github.com/OpenHands/OpenHands/releases/tag/v1.25.0) +- [Compare v1.24.0 to v1.25.0](https://github.com/OpenHands/OpenHands/compare/v1.24.0...v1.25.0) From 4b2104dcc6c64c50238db99b3cfc21b566a8d494 Mon Sep 17 00:00:00 2001 From: Devin Date: Tue, 6 Oct 2026 12:45:09 -0400 Subject: [PATCH 2/2] Update language in model router steps and remove creator information that is cloud only --- openhands/usage/agent-canvas/managing-automations.mdx | 10 ---------- openhands/usage/agent-canvas/model-configuration.mdx | 7 ++++--- 2 files changed, 4 insertions(+), 13 deletions(-) diff --git a/openhands/usage/agent-canvas/managing-automations.mdx b/openhands/usage/agent-canvas/managing-automations.mdx index bab7fedf6..f2efa3d6b 100644 --- a/openhands/usage/agent-canvas/managing-automations.mdx +++ b/openhands/usage/agent-canvas/managing-automations.mdx @@ -21,16 +21,6 @@ Click an automation to open its detail view. The detail view shows: - LLM profile used for runs - Recent run history and status -### Filter by Creator - -On OpenHands Cloud, the Automate view includes a **Filter by creator** control with `Anyone`, `Me`, and `Others` options. - -- `Anyone` shows every automation you can see. -- `Me` shows only automations you created. -- `Others` shows automations created by other members. - -The filter is applied by the backend, so it returns matching automations even when they are not on the first page of results. - ### Run Statuses A run can be `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, or `SKIPPED`. A `SKIPPED` run can occur when the backend reaches its concurrency limit. Future backend statuses appear as a neutral status badge so they do not prevent you from viewing the automation. diff --git a/openhands/usage/agent-canvas/model-configuration.mdx b/openhands/usage/agent-canvas/model-configuration.mdx index 8a28a301e..c05bc5b5a 100644 --- a/openhands/usage/agent-canvas/model-configuration.mdx +++ b/openhands/usage/agent-canvas/model-configuration.mdx @@ -45,10 +45,11 @@ To create a router: 1. Open `Settings > LLM` and select `Model Router`. 2. Select `Add Model Router`. -3. Choose a template: `Add OpenHands Router Pro`, `Add OpenHands Router Flash`, or `Custom`. Router templates let you keep `Don't create profiles` so the template does not add LLM profiles of its own. -4. Review the generated configuration, then save the router. +3. Choose a template: `Add OpenHands Router Pro`, `Add OpenHands Router Flash`, or `Custom`. The Custom option gives you a blank slate to build your own Model Router. +4. Review the prompt template, model table, and then select one of your saved LLM connections so the router can add any missing LLM profiles needed for that router. +5. Review the generated configuration, then save the router. Any needed LLM profiles will be added if you selected an LLM Connection which can take a few moments. -The Model Router settings include a **Run on first message** toggle. When enabled, the first message of every new conversation is routed through the active Model Router before the agent proceeds. The toggle is off by default; Agent Canvas turns it on automatically when you create the first router. Its state is saved with the backend settings, so it persists across reloads. +The Model Router settings include a **Run on first message** toggle. When enabled, the first message of every new conversation is routed through the active Model Router before the agent proceeds. The toggle is off by default but it will be enabled automatically when you add your first router. Model routing requires a backend that supports it. If the connected backend does not, the `Model Router` section reports that the backend does not support model routing yet and asks you to update the agent server.