diff --git a/llms-full.txt b/llms-full.txt index 32c7d659..e6f82afd 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -13210,6 +13210,39 @@ This is useful when: - Letting users edit agent configuration in a form-based UI - Rehydrating the same agent setup in another process +## Load Persisted Settings + +`model_validate` only accepts payloads that already match the current schema. Use `from_persisted` for data written by an older SDK version: it applies the registered schema migrations first, then validates the migrated payload against the class you call it on. + +```python icon="python" focus={1} +restored = OpenHandsAgentSettings.from_persisted(payload) +``` + +`from_persisted` is defined on `AgentSettingsBase`, so it is a concrete-variant loader: `OpenHandsAgentSettings.from_persisted()` returns an `OpenHandsAgentSettings` and `ACPAgentSettings.from_persisted()` returns an `ACPAgentSettings`. When you do not know which variant a payload holds, use `validate_agent_settings` (also in `openhands.sdk.settings`) instead — it dispatches across the settings union. + +Passing an already-validated instance of that variant returns it unchanged, so its secrets are preserved without a lossy serialization round trip. + + +The deprecated `agent_kind="llm"` discriminator is only rewritten while migrating between schema versions. A payload that is already at the current schema version but still carries `agent_kind="llm"` is therefore rejected by `OpenHandsAgentSettings.from_persisted`. Load those payloads with `validate_agent_settings`, which canonicalizes the discriminator unconditionally. + + +### Encrypted Payloads + +Secret-bearing fields only decrypt when you pass the same validation context that was used to write them. + +```python icon="python" focus={2} +persisted = settings.model_dump(mode="json", context={"cipher": cipher}) +restored = OpenHandsAgentSettings.from_persisted(persisted, context={"cipher": cipher}) +``` + +### Errors + +| Exception | Raised when | +|-----------|-------------| +| `TypeError` | The payload is not a mapping or `BaseModel`, or its `schema_version` is not an integer. | +| `ValueError` | `schema_version` is negative, newer than the supported version, or has no registered migration. | +| `pydantic.ValidationError` | The migrated payload is invalid for the class you called `from_persisted` on. | + ## Create an Agent from Settings Once validated, create a working agent directly from the settings object. @@ -18191,9 +18224,9 @@ Hooks let you observe and customize key lifecycle moments in the SDK without for ## Exit Codes -Command hooks (shell scripts) signal their result through their exit code — -[agent-based hooks](#agent-based-hooks) return a JSON decision instead. The SDK -matches the +Command hooks (shell scripts) signal their result through their exit code. +[Prompt-based hooks](#prompt-based-hooks) and +[agent-based hooks](#agent-based-hooks) return a JSON decision instead. The SDK matches the [Claude Code hook contract](https://docs.claude.com/en/docs/claude-code/hooks): - **`0` — success.** The operation proceeds. `stdout` is parsed as JSON for @@ -18218,6 +18251,20 @@ policy must exit with `2`. - Isolation: hooks run outside the agent loop logic, avoiding core modifications - Composition: enable or disable hooks per environment (local vs. prod) +## Execution Modes + +Hook definitions support three execution modes: + +| `type` | Evaluator | Tool access | Best for | +|--------|-----------|-------------|----------| +| `command` (default) | Shell command | Through the script | Deterministic checks and integrations | +| `prompt` | One LLM completion | No | Semantic decisions based only on the hook event | +| `agent` | Short-lived sub-agent | Optional allowlist | Decisions that require workspace investigation | + +Use the least powerful mode that can make the decision. Command hooks are the +most deterministic. Prompt hooks add model judgment with one completion. Agent +hooks add an agent loop and tools when the event payload is not enough. + ## Ready-to-run Example @@ -18458,6 +18505,149 @@ exit 0 +## Prompt-based Hooks + +Set `type="prompt"` to evaluate a hook event with one LLM completion. Prompt +hooks are useful when a decision needs semantic judgment but all required +context is already present in the `HookEvent` payload. For example, a +`PreToolUse` policy can evaluate the intent of a terminal command without +starting a tool-using sub-agent. + +```python +HookDefinition( + type=HookType.PROMPT, + name="terminal-safety", + prompt="Deny terminal commands that recursively delete files ...", + timeout=30, +) +``` + +Key fields on a prompt `HookDefinition`: + +- `name` — identifies the hook in logs, events, and its stable + `prompt-hook:` metrics bucket. +- `prompt` — the trusted policy used to evaluate each matching event. +- `timeout` — the timeout applied to the copied hook LLM. + +The hook uses the conversation's current LLM, including changes made through +model or profile switching. The executor copies that LLM so the hook has an +isolated timeout, usage ID, and metrics. Hook spend is merged back into the +parent conversation's metrics. The SDK selects Chat Completions or the Responses +API from the model's capabilities. Prompt hooks are single-shot and non-streaming, +regardless of the parent LLM's streaming setting. + +The policy is placed in system context. The serialized event is sent in a +separate user message and marked as untrusted data, so instructions embedded in +tool input or output are not treated as hook policy. The model is asked to +return the shared hook result contract: + +```json +{"decision": "allow" | "deny", "reason": ""} +``` + +If the conversation has no LLM, the provider call fails, or the response does +not contain a valid decision, the hook falls open with `decision="allow"` and +`success=False`. This lets consumers distinguish an execution failure from a +deliberate allow verdict. + + +Prompt hooks cannot inspect files, run commands, or access conversation history +beyond data included in the hook event. Use an [agent-based hook](#agent-based-hooks) +when the evaluator must gather more context before deciding. + + + +This example is available on GitHub: [examples/01_standalone_sdk/57_prompt_hooks](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/57_prompt_hooks/) + + +```python icon="python" expandable examples/01_standalone_sdk/57_prompt_hooks/main.py +"""OpenHands Agent SDK - prompt-based hooks example. + +Evaluates two synthetic PreToolUse events with one LLM completion each. The +commands are only event data: this example never executes them. +""" + +import os +import tempfile +from pathlib import Path + +from pydantic import SecretStr + +from openhands.sdk import LLM +from openhands.sdk.conversation.conversation_stats import ConversationStats +from openhands.sdk.hooks import ( + HookConfig, + HookDefinition, + HookManager, + HookMatcher, + HookType, +) + + +api_key = os.getenv("LLM_API_KEY") +assert api_key is not None, "LLM_API_KEY environment variable is not set." + +llm = LLM( + usage_id="agent", + model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"), + base_url=os.getenv("LLM_BASE_URL"), + api_key=SecretStr(api_key), +) + +TERMINAL_POLICY = """Evaluate the semantic intent of a terminal command. +Deny commands that recursively delete files, read credentials or sensitive +system files, modify the host system, or exfiltrate data. Allow read-only +workspace inspection, builds, and test commands. When uncertain, deny and give +a concise reason.""" + +hook_config = HookConfig( + pre_tool_use=[ + HookMatcher( + matcher="terminal", + hooks=[ + HookDefinition( + type=HookType.PROMPT, + name="terminal-safety", + prompt=TERMINAL_POLICY, + timeout=30, + ) + ], + ) + ] +) + +cases = [ + ("python -m pytest -q", True), + ("find / -type f -delete", False), +] + +with tempfile.TemporaryDirectory() as tmpdir: + stats = ConversationStats() + manager = HookManager( + config=hook_config, + working_dir=str(Path(tmpdir)), + session_id="prompt-hook-example", + llm=llm, + conversation_stats=stats, + ) + + for command, expected_to_continue in cases: + should_continue, results = manager.run_pre_tool_use( + tool_name="terminal", + tool_input={"command": command}, + ) + result = results[0] + verdict = "ALLOW" if should_continue else "DENY" + print(f"{verdict:5} {command}") + print(f" {result.reason}") + assert should_continue is expected_to_continue + + cost = stats.get_combined_metrics().accumulated_cost + print(f"\nEXAMPLE_COST: {cost}") +``` + + + ## Agent-based Hooks Besides shell scripts, a hook can delegate its decision to an LLM-driven @@ -25801,6 +25991,56 @@ agent_context = AgentContext(skills=list(skills.values())) - **[MCP Integration](/sdk/guides/mcp)** - Connect external tool servers - **[Confirmation Mode](/sdk/guides/security)** - Add execution approval +### Structured Output +Source: https://docs.openhands.dev/sdk/guides/structured-output.md + +import RunExampleCode from "/sdk/shared-snippets/how-to-run-example.mdx"; + +Pass a Pydantic model (or a JSON Schema dict) as a tool's `response_schema`. Its fields are merged into the schema the LLM sees, so the model must populate them when it calls that tool, and the reply is validated on receipt — no prompting for a format, no output parsing. + +```python +class ProjectFacts(BaseModel): + description: str = Field(description="One-paragraph description of the project.") + facts: list[str] = Field(description="Three concise, distinct facts.") + + +agent = Agent( + llm=llm, + tools=[Tool(name="FinishTool", params={"response_schema": ProjectFacts})], +) +``` + +The tool keeps its own arguments — `FinishTool` still takes `message`, now alongside `description` and `facts`. This works on any tool, including [custom](/sdk/guides/custom-tools) and [MCP](/sdk/guides/mcp) tools. + +## Reading results + +Resolved tools live on `agent.tools_map`. Use `parse_last_response()` for the most recent call, or `parse_response(action)` for a specific one: + +```python +finish_tool = agent.tools_map["finish"] +facts = cast(ProjectFacts | None, finish_tool.parse_last_response(conversation.state.events)) +``` + +`parse_last_response()` returns `None` if the tool has not been called. With a JSON Schema dict instead of a model, both methods return a validated `dict`. + + +`parse_last_response()` re-reads the tool call, so it works after a conversation is persisted and reloaded. `action.structured_output` is in-memory only — it is not serialized with the event and comes back `None` after a round-trip, so prefer the parse methods. + + +## Constraints + +- **Reserved names.** A schema may not declare `kind`, `security_risk`, `structured_output`, or `summary`, nor reuse one of the tool's own field names (e.g. `message` on `FinishTool`). Both raise a `ValueError` when the tool is resolved. +- **One tool per spec.** A spec that resolves to a tool set is rejected; attach the schema to the individual tool instead. +- **Scoped to its tool.** A model may try to send the schema fields when calling *other* tools; those calls are rejected as unexpected arguments and the agent retries. + +## Ready-to-run Example + +```python icon="python" expandable examples/01_standalone_sdk/56_structured_output.py +# content is auto-synced +``` + + + ### Task Tool Set Source: https://docs.openhands.dev/sdk/guides/task-tool-set.md @@ -29030,7 +29270,7 @@ If you choose OpenHands, the setup flow also configures the LLM profile that the ### Agent Canvas Architecture Source: https://docs.openhands.dev/openhands/usage/agent-canvas/architecture.md -Agent Canvas is the open-source browser client and control center for OpenHands conversations and automations. It presents backend state and sends requests to backend services; it is not an agent runtime or sandbox. Agent Server or an ACP agent process executes tools, and the selected workspace or sandbox provides the execution boundary. +Agent Canvas is the open-source browser client and control center for OpenHands conversations and automations. It presents backend state and sends requests to backend services; it is not an agent runtime or sandbox. Agent Server or an ACP agent CLI executes tools, and the selected workspace or sandbox provides the execution boundary. ## Core Components @@ -29041,39 +29281,10 @@ Agent Canvas is the open-source browser client and control center for OpenHands | **Automation Server** | Stores schedules and event triggers, tracks runs, and dispatches conversations | [`OpenHands/automation`](https://github.com/OpenHands/automation) | | **Workspace or sandbox** | Defines which files, processes, credentials, and networks an agent can access | Deployment-specific | -Sandbox Server is a community-driven standalone API and sandbox control plane. It is not a core Agent Canvas backend or a supported deployment option. [Learn more about Sandbox Server](https://github.com/OpenHands/sandbox-server). +Sandbox Server is a community-driven standalone API and sandbox control plane. [Learn more about Sandbox Server](https://github.com/OpenHands/sandbox-server). ## Service Relationships -```mermaid -%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 45}} }%% -flowchart TB - Browser["Browser"] --> Canvas["Agent Canvas
browser client"] - - subgraph Backend["Selected backend"] - AgentServer["Agent Server"] -->|execute agent and tools| Workspace["Workspace or sandbox"] - Automation["Automation Server"] -->|dispatch conversation| AgentServer - end - - Canvas -->|conversations and settings| AgentServer - Canvas -->|schedules, events, and runs| Automation - - subgraph Platform["OpenHands Cloud or Enterprise"] - ControlPlane["Platform control plane"] -->|create and manage| Sandbox["Conversation sandbox"] - Sandbox -->|hosts| PlatformAgentServer["Agent Server"] - end - - Canvas -.->|managed backend| PlatformAgentServer - - classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px - classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px - classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px - classDef service fill:#e9f9ef,stroke:#2f855a,stroke-width:2px - class Canvas primary - class AgentServer,Automation,PlatformAgentServer secondary - class Workspace,Sandbox tertiary - class ControlPlane service -``` The normal browser path is **Browser → Agent Canvas → selected backend**. Agent Server owns conversation execution. Automation Server owns scheduled and event-driven run lifecycle. A backend distribution can expose both services behind one URL, but they remain separate responsibilities. @@ -29096,17 +29307,16 @@ The launcher supports split modes: Docker and Helm packages can also bundle the client and backend services. A bundled deployment changes how services are installed, not which component owns execution or isolation. -## Execution And Isolation +## Execution and Isolation When you send a message, Agent Canvas sends it to the selected backend. Agent Server starts or resumes the conversation, runs the selected agent, invokes tools, updates backend state, and streams events to Canvas. The workspace determines the execution boundary: -| Workspace type | Execution and isolation boundary | -|----------------|----------------------------------| -| **Local process** | Agent Server and tools run directly on the backend host without container isolation. | +| Execution environment | Execution and isolation boundary | +|-----------------------|----------------------------------| +| **Host process** | Agent Server and tools run directly on the backend host without container isolation. If the backend is remote, that host—not the browser's machine—is the execution boundary. | | **Docker or Kubernetes** | Agent Server and tools run inside the configured container or pod with its mounts and network policy. | -| **Remote Agent Server** | Agent Server runs on another machine or in a separate container, with the workspace boundary configured there. | | **OpenHands Cloud or Enterprise** | The managed platform creates and operates the conversation sandbox that hosts Agent Server. | Connecting Canvas to a remote backend does not grant the browser direct access to that backend's filesystem. Canvas displays files and terminal output returned by Agent Server. @@ -29127,14 +29337,14 @@ Switching backends changes which backend-managed conversations, settings, automa | Pattern | Relationship | |---------|--------------| | **Local all-in-one** | The launcher starts Canvas and local backend services on one machine. | -| **Remote Agent Server** | Canvas connects to an Agent Server running on another machine or in a separate container on the same machine. | -| **Self-hosted backend services** | You deploy Agent Server, and optionally Automation Server, on a VM, Docker host, Kubernetes cluster, or Modal. | +| **Self-hosted backend services** | You deploy Agent Server, and optionally Automation Server, in another process, on a VM, in Docker or Kubernetes, or on Modal. Canvas connects to the deployment as a remote backend. | | **Managed platform** | Canvas connects to OpenHands Cloud or OpenHands Enterprise, which operate their backend and sandbox infrastructure. | ## Next Steps - [Install Agent Canvas](/openhands/usage/agent-canvas/setup) - [Connect And Manage Backends](/openhands/usage/agent-canvas/backends) +- [Connect To A Remote Backend](/openhands/usage/agent-canvas/backend-setup/remote) - [Self-Host On A VM](/openhands/usage/agent-canvas/backend-setup/vm) - [Use Docker](/openhands/usage/agent-canvas/backend-setup/docker) - [Agent Server Overview](/sdk/guides/agent-server/overview) @@ -29151,6 +29361,7 @@ A Cloud backend is a good fit when you want to: - Run agents without tying up local resources - Use OpenHands Cloud's managed sandboxes and integrations - Keep your local machine for development while offloading agent work +- Easy Phone & Tablet Access so you can code on the go ## Prerequisites @@ -29847,7 +30058,7 @@ Switch between them from the backend selector depending on what you're working o ### Modal Backend Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/modal.md -Deploy [Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server) on [Modal](https://modal.com) as a remote backend for Agent Canvas. Canvas runs locally on your machine while Agent Server runs on Modal and executes code inside the container—the same execution model as the backend started by `npx @openhands/agent-canvas`. +Deploy [OpenHands](https://github.com/OpenHands/OpenHands) on [Modal](https://modal.com) as a remote backend for Agent Canvas. Canvas runs locally on your machine while the Agent Canvas Backend runs on Modal and executes code inside the container—the same execution model as the backend started by `npx @openhands/agent-canvas`. The agent server runs with full access to the container's filesystem, environment, and network. Anyone with the API key can execute arbitrary code on your Modal container. Keep the API key secret and rotate it if it's ever exposed. @@ -30204,10 +30415,10 @@ Agent Canvas does not distinguish a remote backend by where it runs. It connects A remote backend must provide: - An accessible Agent Server URL. -- An API key when the backend requires authentication. +- An API key. - A workspace or sandbox where Agent Server can execute tools. -To use scheduled or event-driven automations, the backend must also provide Automation Server. +To use scheduled or event-driven automations, the backend must also provide an Automation Server. ## Connect To A Remote Backend @@ -30582,21 +30793,24 @@ Before exposing Agent Canvas beyond an SSH tunnel: ### Backends Source: https://docs.openhands.dev/openhands/usage/agent-canvas/backends.md -A **backend** provides Agent Server and, when automations are enabled, Automation Server. Agent Server runs conversations and tools in a workspace: the folder, mounted project directory, container, or cloud sandbox where the agent reads and writes files. Automation Server manages schedules, events, and run lifecycle. Agent Canvas connects to these services and displays the state of whichever backend is selected. +A **backend** provides [Agent Server](/sdk/guides/agent-server/overview#what-is-a-remote-agent-server) and, when automations are enabled, Automation Server. Agent Server runs conversations and tools in a workspace: the folder, mounted project directory, container, or cloud sandbox where the agent reads and writes files. Automation Server manages schedules, events, and run lifecycle. Agent Canvas connects to these services and displays the state of whichever backend is selected. ## Connecting to a Backend Any Agent Canvas frontend can connect to any Agent Canvas backend. Use the backend switcher in the UI to open **Manage Backends**, where you can add, edit, or remove entries. Each entry stores a display name, host URL, and an API key for authentication. +![Agent Canvas Add Backend dialog on the Agent Server tab with synthetic display name, host URL, and masked API key fields.](/openhands/static/img/agent-canvas-add-backend-agent-server.png) + Settings, LLM configuration, MCP servers, and automations are all scoped to the active backend — switching backends switches all of these. +"Remote" describes how Canvas connects to a backend, not where that backend runs. A remote backend can be a separate process on the same machine, a self-hosted deployment on a VM or container platform, or a managed Cloud or Enterprise service. + ## Recommended Setups | Setup | When to use | How | |-------|-------------|-----| | **Default local** | Quick local work on your machine | Run `agent-canvas`—a local backend is created automatically. | -| **Remote Agent Server** | An Agent Server on another machine or in a separate local container | Add its host URL and API key in `Manage Backends`. See [Remote Backend](/openhands/usage/agent-canvas/backend-setup/remote). | -| **Self-hosted VM** | Always-on server, more powerful hardware, team-shared access, or a full self-hosted Canvas | Run `agent-canvas --backend-only --public` for backend-only mode, or `agent-canvas --public` for the full UI and backend. See [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). | +| **Self-hosted backend** | A separate local process or container, an always-on VM, more powerful hardware, or team-shared access | Deploy the backend services, then add their host URL and API key in `Manage Backends`. See [Remote Backend](/openhands/usage/agent-canvas/backend-setup/remote) and [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). | | **Cloud or Enterprise** | Managed backend and sandbox infrastructure | Connect from `Manage Backends`. See [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud). | ### Conversations @@ -30604,6 +30818,22 @@ Source: https://docs.openhands.dev/openhands/usage/agent-canvas/conversations.md 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. +## Child Conversations + +When an agent uses `launch_child_conversation`, Agent Canvas can launch a child conversation on a local or Cloud target. Local children can use either an isolated worktree or the parent's shared workspace. Cloud children use the repository and branch selected for the launch. + +The child remains linked to its parent, and its result is returned to the parent conversation. Agent Canvas validates the launch inputs before creating the child conversation. + +## Conversation List Controls + +Use the conversation list controls to manage automation runs and visible tags: + +- Choose `All`, `Hide`, or `Only` to include, exclude, or show only automation-run conversations. You can further select individual automation names, including unnamed automations. +- Pinned conversations remain visible when automation-run filtering would otherwise hide them. +- Enable the `Tags` preference to show conversation tag chips. Tags are off by default; when there are more tags than fit, Agent Canvas shows a `+N` chip with the remaining count. + +Agent Canvas omits reserved tags and raw automation IDs from the chips. LLM metadata is also hidden by default. + ## Follow Agent Activity While an agent is running, the composer shows a live activity chip for its current unresolved action, such as reading a file or running a command. If no action-specific label is available, it shows `Thinking`. The chip disappears when the agent pauses or completes its work. @@ -30612,6 +30842,20 @@ While an agent is running, the composer shows a live activity chip for its curre If a message fails to send, select `Retry` to send it again or `Dismiss` to remove the failed message bubble. Dismissing a message does not restore its text to the composer. +## Inline Markdown Artifact Previews + +When an agent creates a Markdown file, Agent Canvas renders it inline as a height-limited rich preview with an internal scrollbar instead of showing only the raw file content. Select `View` to open the full file in the Files drawer. + +## 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. + +Click the meter to open the usage preview, then click "Usage" to see the full usage panel which shows token usage and provider balance details. You can manually compact the conversation to reduce context by selecting "Compact context" in the usage preview or usage panel. + + + The meter only appears for models that report a context window size. Models that do not report one will not show a meter. + + ## Branch From a Message Use `Branch from here` on a message when you want to explore a different path without changing the original conversation. @@ -30726,6 +30970,29 @@ The export is generated locally in your browser from the events Agent Canvas alr For very large conversations, Agent Canvas loads the full event history before generating the file. This may take a moment. On cloud backends, the export uses the events the app currently has loaded. +## Archive a Conversation + +Archiving a conversation hides it from the sidebar list without deleting it. The conversation's full history stays on the backend, and you can unarchive it at any time. + +**To archive a conversation:** + +1. Open the conversation card menu in the sidebar. +2. Select `Archive`. +3. Confirm in the dialog that appears. + +The conversation disappears from the default sidebar list. An archived conversation shows an `Archived` chip when revealed. + +**To view or restore archived conversations:** + +1. Open the panel filter menu in the sidebar. +2. Enable `Show archived`. +3. Archived conversations reappear with an `Archived` chip. +4. Open an archived conversation's menu and select `Unarchive` to restore it to the default list. + + + Archive state is stored per backend in your browser's local storage. It does not sync across browsers or machines. The `Delete all` action still deletes archived conversations, including hidden ones. Archiving is non-destructive, but deleting is permanent. + + ## Related Guides - [Fork a Conversation](/sdk/guides/convo-fork) @@ -30877,8 +31144,8 @@ Agent Canvas separates **Customize** from **Settings**. Open the top-level `Customize` area to manage: -- [Skills](/overview/skills) - [MCP Servers](/openhands/usage/settings/mcp-settings) +- [Skills](/overview/skills) - [Plugins](/openhands/usage/agent-canvas/plugins) Use the section navigation inside `Customize` to switch between these pages. @@ -30921,9 +31188,10 @@ The `Settings` area currently includes the following sections: | `Application` | UI-level preferences and app behavior | | `Secrets` | Stored secrets used by the active backend | -On local backends, the `LLM` page also includes an `Available Profiles` area for saved profiles. -In `Settings > Application`, the **Conversation titles** setting selects the LLM profile used to generate conversation titles. **Automatic** uses the active local LLM profile; you can choose another saved profile, like a small, cheap LLM, when you want titles generated independently from the model selected for agent work. The same page shows the installed Agent Canvas version, update availability, and a **Check for updates** button. +In `Settings > Application`, the **Conversation titles** setting selects the LLM profile used to generate conversation titles. **Automatic** uses the active local LLM profile; you can choose another saved profile, like a small, cheap LLM, when you want titles generated independently from the model selected for agent work. + +The main settings nav also shows the installed version of Agent Canvas with a manual **Check for updates** button. When an update is available click on the tile to view details and update information. 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. @@ -31095,8 +31363,20 @@ Use an OpenHands LLM API key when you want Agent Canvas to access models through 2. In the **Basic** tab, select `OpenHands`, choose a model, and add the key. 3. Save the profile and start a new conversation. +While using OpenHands as your LLM provider you will see OpenHands-routed model IDs as marked as`Free`. These models change as we have promotional periods where we can offer them without any additional token cost. + +The `Free` label applies only to those full `openhands/` routes. Endpoints from other providers with similar model names may have separate billing. The label remains visible after you select one of these models. + +When you create a local LLM profile, the form initially selects `openhands/kimi-k3` and derives the profile name `kimi-k3`. You can change either value before saving. + For key details and available models, see [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms). +### Pre-Save Validation + +When you save an LLM profile, the configuration is validated against the backend before it is persisted. If validation fails — for example, because the API key is rejected or the model is unavailable — the save is blocked and the backend error is shown. The save button displays a validating state while the check runs. + +Older backends that do not support validation (they return a `404` for the validation endpoint) skip this check and save normally. + ### Local OpenAI-Compatible Endpoint A local server can be LM Studio, Ollama, vLLM, SGLang, or another service that exposes an OpenAI-compatible API. In the **Advanced** tab, enter the provider, exact model ID, endpoint base URL, and the required API key or a placeholder value when the server does not require one. @@ -31131,6 +31411,8 @@ LLM profiles are separate from [Agent Profiles](/openhands/usage/agent-canvas/ag The available profiles list shows each profile's name, configured model, and whether it is active. Use a profile's menu to edit or rename it, set it as the active profile for new conversations, or delete it when you no longer need it. +![Agent Canvas LLM settings showing two synthetic saved profiles, one marked as the default, with its profile actions menu open.](/openhands/static/img/agent-canvas-llm-profiles-manager.png) + ## Switching Profiles in a Conversation You can switch profiles from the profile selector in the chat input or with the `/model` command: @@ -31183,7 +31465,7 @@ The **Automate** view in Agent Canvas is the in-app control center for your auto ## Browse and inspect automations -Open the **Automate** tab in the sidebar to see all automations on the active backend. Each row shows the automation name, trigger type, and enabled state. +Open the **Automate** tab in the sidebar to see all automations on the active backend. Each row shows the automation name, trigger type, and enabled state. When the active backend is healthy but has no automations, the Automate pane remains available and includes an option to add one. Click an automation to open its detail view. The detail view shows: @@ -31196,6 +31478,12 @@ Click an automation to open its detail view. The detail view shows: 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. +### Activity Log Costs and Exports + +The Activity Log displays a completed run's reported LLM cost in USD to four decimal places. A measured zero cost appears as `$0.0000`; when the backend does not report a cost, no cost appears in the log. + +Use the Activity Log export controls to download run data as CSV or JSON. Both formats include a raw numeric `cost` field for every run. An unavailable cost is exported as `null`. + ## Enable and disable automations Toggle an automation on or off from the kebab menu (⋮) on the automation row, or from the detail view. Disabled automations do not fire on their scheduled trigger or in response to events, but their configuration is preserved. @@ -31256,6 +31544,9 @@ You can import an automation from a JSON file previously exported by Agent Canva 2. Click **Import automation** at the top of the list. 3. Pick the `.json` file to import. 4. Review the preview — it shows the automation's name, trigger type, and prompt. + +![Agent Canvas import automation dialog previewing the Weekly Documentation Review name, schedule, and prompt before import](/openhands/static/img/agent-canvas-automation-import-preview.png) + 5. Confirm to create the automation. Imported automations are created **disabled**. After importing, open the automation from the list, review its configuration, and enable it when ready. @@ -31343,16 +31634,27 @@ You can also test a preview build of the native desktop app. [Try the desktop pr Agent Canvas is the browser client. It connects to backend services that own execution and persistent state: -| Component | Responsibility | -|-----------|----------------| -| **Agent Canvas** | Displays conversations, files, terminals, settings, backends, and automations. | -| **Agent Server** | Runs conversations, agents, tools, and workspace operations. | -| **Automation Server** | Manages schedules, event triggers, dispatch, and run history. | -| **Workspace or sandbox** | Defines which files, processes, credentials, and networks the agent can access. | +| Concept | What It Means | Why It Matters | +|-------|---------------|----------------| +| **Browser UI** | The web interface you open in your browser. | This is where you chat, inspect files, manage settings, and configure automations. | +| **Backend** | The agent server that runs conversations, tools, settings, secrets, and automations. | This determines where the agent runs and what machine or sandbox it can access. | +| **Workspace** | The folder, repository, container mount, or cloud sandbox the agent works in. | This determines which files the agent can read and write. | +| **Agent and model** | The OpenHands agent or an ACP agent, plus the model credentials it uses. | This determines which LLM or provider receives conversation context and powers the agent. | - - Agent Canvas does not execute tools or provide sandbox isolation. Agent Server or an ACP process executes tools, and the selected workspace or sandbox provides the execution boundary. - +```mermaid +flowchart LR + browser["Browser UI"] --> backend["Selected backend"] + backend --> conversation["Conversation and agent"] + conversation --> model["Model access"] + conversation --> workspace["Workspace and tools"] + + classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px + classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px + classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px + class browser primary + class backend,conversation secondary + class model,workspace tertiary +``` The `agent-canvas` launcher can package the client and backend services into one local stack. You can also run the client separately and connect it to services on a VM, in Docker or Kubernetes, or through OpenHands Cloud or OpenHands Enterprise. @@ -31532,7 +31834,7 @@ Agent Canvas ships with a set of pre-built automations for the most common agent --- -Backends created by the `agent-canvas` launcher include Automation Server, so they can run agents on a schedule or in response to external events. Other backends must provide a compatible automation service for these features. +Backends created by the `agent-canvas` launcher include Automation Server, so they can run agents on a schedule or in response to external events. ## What You Can Do @@ -31557,6 +31859,10 @@ For recommended automations that support a direct form setup, Agent Canvas check For a detailed walkthrough, see [Creating Automations](/openhands/usage/automations/creating-automations). + + Some recommended automations depend on integrations that cannot be auto-installed as MCP servers on this backend (for example, Jira's HTTP/OpenAPI-only integration). These appear on the recommendation card with a `Needs external setup` label. The `MCPs to connect` count only covers integrations the install flow can connect automatically. You must configure externally-hosted integrations yourself before the automation can use them. + + 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 @@ -31922,7 +32228,7 @@ Source: https://docs.openhands.dev/openhands/usage/agent-canvas/setup.md The `agent-canvas` launcher can run the Canvas client with Agent Server, Automation Server, and ingress as an all-in-one local stack. Use npm or npx for direct local execution, or Docker for a containerized stack with explicit project mounts. You can also run the client separately and connect it to an existing backend. - Agent Server and ACP processes can run shell commands, read files, write files, and use connected tools. Agent Canvas is the client and does not provide isolation. Treat the machine, container, or sandbox where the backend runs as trusted infrastructure. Before exposing backend services to a network you do not control, review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). + Treat agents and ACP processes as untrusted: they can run shell commands, read files, write files, and use connected tools within their execution environment. Agent Canvas is the client and does not provide isolation. If the backend runs directly on your machine, the agent can act with your user account's permissions. Use a container, sandbox, or VM to define a tighter boundary. Before exposing backend services to a network you do not control, review [VM / Self-Hosted Installation](/openhands/usage/agent-canvas/backend-setup/vm). ## Choose An Install Method @@ -32515,6 +32821,11 @@ Common causes: - A LiteLLM proxy token is invalid. - An OpenAI-compatible provider needs the provider, model, base URL, and key to line up. +Agent Canvas classifies conversation errors and presents them with distinct banner variants: + +- **Recoverable errors** (such as authentication failures) are shown with a warning banner, indicating you can take action — for example, updating an API key or switching models. +- **Internal errors** are shown with an error banner, indicating a problem that may require restarting the conversation or backend. + For model setup details, see: - [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) @@ -32660,7 +32971,7 @@ https://github.com/OpenHands/OpenHands/assets/38853559/f592a192-e86c-4f48-ad31-d _Example of CodeActAgent with `gpt-4-turbo-2024-04-09` performing a data science task (linear regression)_. -### Sandbox Server REST API (V1) +### REST API (V1) Source: https://docs.openhands.dev/openhands/usage/api/v1.md The [OpenHands Sandbox Server](https://github.com/OpenHands/sandbox-server) is the standalone API and sandbox control plane extracted from the former OpenHands monorepo. It exposes conversation and sandbox resources without bundling a frontend. @@ -32675,7 +32986,7 @@ Sandbox Server V1 REST endpoints are mounted under: - /api/v1 -Use these endpoints to integrate with the Sandbox Server control plane. Agent Canvas is the browser client for compatible deployments; Sandbox Server itself does not include a frontend. +Use these endpoints to integrate with the Sandbox Server control plane. Sandbox Server itself does not include a frontend. ## Key resources @@ -32741,7 +33052,7 @@ When asking OpenHands to create an automation, include: - **What it should do**: Describe the task clearly - **When it should run**: Daily, weekly, every hour, etc. - **Timezone** (optional): Defaults to UTC if not specified -- **Run timeout** (optional): Defaults to 10 minutes; maximum 30 minutes +- **Run timeout** (optional): Defaults to 10 minutes; the maximum depends on your deployment - **Name** (optional): The agent can suggest one based on your description - **Plugins** (optional): Mention specific plugins if you need extended capabilities @@ -33166,7 +33477,7 @@ Update the "Weekly Cleanup" automation to run on Sundays at 2 AM UTC Set the "Weekly Cleanup" automation timeout to 20 minutes ``` -Timeouts can be up to 30 minutes. Runs that exceed their timeout fail automatically. +The maximum timeout depends on your deployment. Runs that exceed their timeout fail automatically. ## Running Manually @@ -33196,6 +33507,8 @@ Each run creates a conversation that automatically appears in your conversations - **Continue** if you want to interact with the sandbox - **Debug** if something went wrong +In an automation's `Activity Log`, use `Export JSON` or `Export CSV` to download its complete run history. + Automations are user-scoped, so all your automation runs appear alongside your regular conversations. Look for them in your conversations list after each scheduled run. @@ -36393,74 +36706,97 @@ AWS Bedrock provides access to foundation models from Amazon and third-party pro ### Environment Variables -When running OpenHands with Docker, set the following environment variables using `-e`: +When running Agent Canvas with the [official Docker image](/openhands/usage/agent-canvas/backend-setup/docker), add these options to the documented `docker run` command: ```bash -docker run -it --pull=always \ - -e LLM_AWS_ACCESS_KEY_ID="your-access-key-id" \ - -e LLM_AWS_SECRET_ACCESS_KEY="your-secret-access-key" \ - -e LLM_AWS_REGION_NAME="us-east-1" \ - ... +--env LLM_AWS_ACCESS_KEY_ID="your-access-key-id" \ +--env LLM_AWS_SECRET_ACCESS_KEY="your-secret-access-key" \ +--env LLM_AWS_REGION_NAME="us-east-1" ``` +The official `ghcr.io/openhands/agent-canvas:latest` image includes the AWS SDK for Python (`boto3`). + Make sure you have enabled the Bedrock models you want to use in the AWS Console. Go to **Amazon Bedrock** → **Model access** and request access to the models you need. ### UI Configuration -In the OpenHands UI Settings under the `LLM` tab: +In Agent Canvas: -1. Enable `Advanced` options -2. Set the following: - - `Custom Model` to the Bedrock model ID (see [Model IDs](#model-ids)) - - Leave `Base URL` empty (Bedrock uses AWS endpoints automatically) - - Leave `API Key` empty (authentication is handled via AWS credentials) +1. Open `Settings > LLM` and enable the `Advanced` options. +2. Set `Custom Model` to the Bedrock model or inference profile ID. See [Model IDs](#model-ids). +3. Leave `Base URL` empty because Bedrock uses AWS endpoints automatically. +4. Leave `API Key` empty because authentication is handled through your AWS credentials. +5. Save the profile and start a new conversation to test it. + +See [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles) for more information about profile settings. ### Model IDs Bedrock model IDs are managed by AWS and may change over time. Use the exact **Model ID** from the AWS Console or the AWS documentation (no `bedrock/` prefix). Example format: + - `Custom Model`: `anthropic.claude-3-5-sonnet-20241022-v2:0` For a complete list of available models, see the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html). ### Cross-Region Inference -Some Bedrock models can be invoked across regions by prefixing the model ID with the target region (for example, `us.`): +Some models must be invoked through a cross-region inference profile rather than their direct foundation model ID. Inference profile IDs include a geographic prefix such as `us.`. + +For example, use: -- `Custom Model`: `.` +- `Custom Model`: `us.anthropic.claude-sonnet-4-5-20250929-v1:0` -No additional environment variable configuration is needed—keep using your normal Bedrock setup and credentials. +instead of the direct model ID: + +- `anthropic.claude-sonnet-4-5-20250929-v1:0` + +No additional environment variables are required. Keep using the AWS region where you configured Bedrock access and your existing credentials. See [Increase throughput with cross-region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) for supported profiles and regions. ### Using IAM Roles (Alternative to Access Keys) -If running OpenHands on AWS infrastructure (EC2, ECS, Lambda), you can use IAM roles instead of access keys: +If running OpenHands on AWS infrastructure such as EC2, ECS, or Lambda, you can use IAM roles instead of access keys: -1. Attach an IAM role with Bedrock permissions to your compute resource -2. Omit the `LLM_AWS_ACCESS_KEY_ID` and `LLM_AWS_SECRET_ACCESS_KEY` environment variables -3. The AWS SDK will automatically use the instance role credentials +1. Attach an IAM role with Bedrock permissions to your compute resource. +2. Omit the `LLM_AWS_ACCESS_KEY_ID` and `LLM_AWS_SECRET_ACCESS_KEY` environment variables. +3. The AWS SDK automatically uses the instance role credentials. ### Troubleshooting #### "No module named 'boto3'" Error If you encounter this error: -``` + +```text litellm.APIConnectionError: No module named 'boto3' ModuleNotFoundError: No module named 'boto3' ``` -This means you're using an older version of the OpenHands Docker image that doesn't include the AWS SDK. Update to the latest version: +First identify how you installed Agent Canvas: -```bash -docker pull docker.openhands.dev/openhands/openhands:latest +- **Docker:** The current `ghcr.io/openhands/agent-canvas:latest` image includes `boto3`. Pull the latest image and recreate the container: + + ```bash + docker pull ghcr.io/openhands/agent-canvas:latest + ``` + +- **npm or npx:** The Python environment managed by the npm distribution may not include the optional Bedrock dependency. Follow [OpenHands issue #16578](https://github.com/OpenHands/OpenHands/issues/16578) for the package fix. Use the official Agent Canvas Docker image if you need Bedrock while that issue remains open. + +Do not install `boto3` into a temporary uv archive environment because Agent Canvas may recreate that environment. + +#### On-Demand Throughput Is Not Supported + +Some foundation model IDs cannot be invoked directly and return an error similar to: + +```text +Invocation of model ID ... with on-demand throughput isn't supported. +Retry your request with the ID or ARN of an inference profile that contains this model. ``` - -This issue is resolved in recent OpenHands releases. If you still see it, upgrade to `latest` (or a recent release tag). - +Use the corresponding inference profile ID or ARN, such as `us.anthropic.claude-sonnet-4-5-20250929-v1:0`. This error does not indicate a credential, model access, or `boto3` problem. #### Access Denied Errors @@ -38285,6 +38621,12 @@ for new conversations. Alternatively, you can click the `Add LLM Profile` button in the Available Profiles section to create a new profile directly. + +When saving a local LLM profile, the configuration is validated against the backend before it is persisted. If validation +fails (for example, an invalid API key or unavailable model), the save is blocked and the error is shown. Older backends +that do not support validation skip this check and save normally. + + ### Managing LLM Profiles You can manage your saved profiles in the `Available Profiles` section of the LLM settings page. Each profile shows: @@ -38618,7 +38960,7 @@ Other options include: In Agent Canvas, open `Customize > MCP Servers` to manage installed MCP servers. Use the control on an installed server card to disable it without deleting its configuration or saved credentials. Disabled servers are unavailable to new conversations until you enable them again. -Use the editor's delete action only when you want to remove the server configuration. Editing a disabled server does not enable it. +Adding, editing, renaming, or deleting one server does not remove saved credentials for your other servers. Use the editor's delete action only when you want to remove that server configuration. Editing a disabled server does not enable it. ## OAuth Authentication @@ -39647,6 +39989,251 @@ After creating the automation: - [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration for OpenHands Cloud - [Skills Documentation](/overview/skills) - Learn more about OpenHands skills +### Agent-Driven Daily Workflow +Source: https://docs.openhands.dev/openhands/usage/use-cases/daily-workflow.md + +