From 473c8a9d141619f3a44f09f5b479e4747b202c80 Mon Sep 17 00:00:00 2001 From: enyst <6080905+enyst@users.noreply.github.com> Date: Mon, 17 Aug 2026 03:19:28 +0000 Subject: [PATCH] docs: sync llms context files --- llms-full.txt | 2356 ++++++++++++++++++++++++++++++++++++++++--------- llms.txt | 11 +- 2 files changed, 1937 insertions(+), 430 deletions(-) diff --git a/llms-full.txt b/llms-full.txt index 32c7d659..9c446b1b 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -18191,9 +18191,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 +18218,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 +18472,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 +25958,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 +29237,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 +29248,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 +29274,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 +29304,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 +29328,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 +30025,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 +30382,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,7 +30760,7 @@ 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 @@ -30590,13 +30768,14 @@ Any Agent Canvas frontend can connect to any Agent Canvas backend. Use the backe 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 +30783,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 +30807,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 +30935,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 +31109,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 +31153,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. @@ -31183,7 +31416,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 +31429,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. @@ -31343,16 +31582,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 +31782,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 +31807,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 +32176,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 @@ -32660,7 +32914,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 +32929,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 +32995,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 +33420,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 +33450,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. @@ -38618,7 +38874,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,124 +39903,369 @@ 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 -### Dependency Upgrades -Source: https://docs.openhands.dev/openhands/usage/use-cases/dependency-upgrades.md +### Agent-Driven Daily Workflow +Source: https://docs.openhands.dev/openhands/usage/use-cases/daily-workflow.md -Keeping dependencies up to date is essential for security, performance, and access to new features. OpenHands can help you identify outdated dependencies, plan upgrades, handle breaking changes, and validate that your application still works after updates. +