diff --git a/optional-skills/autonomous-ai-agents/openhands/SKILL.md b/optional-skills/autonomous-ai-agents/openhands/SKILL.md new file mode 100644 index 00000000000..5fb51d3dc1f --- /dev/null +++ b/optional-skills/autonomous-ai-agents/openhands/SKILL.md @@ -0,0 +1,149 @@ +--- +name: openhands +description: Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). +version: 0.1.0 +author: Tim Koepsel (xzessmedia), Hermes Agent +license: MIT +platforms: [linux, macos] +metadata: + hermes: + tags: [Coding-Agent, OpenHands, Model-Agnostic, LiteLLM] + related_skills: [claude-code, codex, opencode, hermes-agent] +--- + +# OpenHands CLI + +Delegate coding tasks to the [OpenHands CLI](https://github.com/All-Hands-AI/OpenHands) via the `terminal` tool. OpenHands is model-agnostic: any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM, etc.). + +This skill is the headless-mode wrapper for batch / one-shot delegation. The interactive textual UI is not used from Hermes. + +## When to Use + +- User wants a coding task delegated to OpenHands specifically. +- User wants a coding agent that can run on a non-Anthropic / non-OpenAI provider (DeepSeek, Qwen, Ollama, vLLM, Nous, etc.) — sibling skills `claude-code` and `codex` are tied to one vendor. +- Multi-step file edits + shell commands inside a workspace. + +For Claude-native, prefer `claude-code`. For OpenAI-native, prefer `codex`. For Hermes-native subagents, use `delegate_task`. + +## Prerequisites + +1. Install upstream (requires Python 3.12+ and `uv`): + + ``` + terminal(command="uv tool install openhands --python 3.12") + ``` + + Verify: `openhands --version` (currently `OpenHands CLI 1.16.0` / `SDK v1.21.0` at time of writing). + +2. Pick a model and set env vars for `--override-with-envs`: + + ``` + export LLM_MODEL=openrouter/openai/gpt-4o-mini # or any LiteLLM slug + export LLM_API_KEY=$OPENROUTER_API_KEY + export LLM_BASE_URL=https://openrouter.ai/api/v1 # omit for native OpenAI + ``` + + `LLM_MODEL` uses LiteLLM's full slug. When the provider is OpenRouter the slug is doubly-prefixed: `openrouter//` (e.g. `openrouter/anthropic/claude-sonnet-4.5`). For native Anthropic: `anthropic/claude-sonnet-4-5`. For native OpenAI: `openai/gpt-4o-mini`. + +3. Suppress the startup banner so JSON output isn't preceded by ASCII art: + + ``` + export OPENHANDS_SUPPRESS_BANNER=1 + ``` + +## How to Run + +Always invoke through the `terminal` tool. Always pass `--headless --json --override-with-envs --exit-without-confirmation` for automation. + +### One-shot task + +``` +terminal( + command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'", + workdir="/path/to/project", + timeout=600 +) +``` + +### Background for long tasks + +``` +terminal(command="", workdir="/path/to/project", background=true, notify_on_complete=true) +process(action="poll", session_id="") +process(action="log", session_id="") +``` + +### Resume a previous conversation + +OpenHands prints `Conversation ID: <32-hex>` and a `Hint: openhands --resume ` line at the end of each run. Use the dashed form to resume: + +``` +terminal( + command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume -t 'Now fix the bug you found'", + workdir="/path/to/project" +) +``` + +## Real Flag List + +Verified against `openhands --help` (CLI 1.16.0). Anything not in this table is not a flag — pass it via env var or settings file. + +| Flag | Effect | +|------|--------| +| `--headless` | No UI, requires `-t` or `-f`. Auto-approves all actions (no `--llm-approve` in this mode). | +| `--json` | JSONL event stream (requires `--headless`). | +| `-t TEXT` | Task prompt. | +| `-f PATH` | Read task from file. | +| `--resume [ID]` | Resume conversation. No ID → list recent. | +| `--last` | Resume most recent (with `--resume`). | +| `--override-with-envs` | Apply `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` env vars. Without this, OpenHands uses `~/.openhands/settings.json` and ignores the env. | +| `--exit-without-confirmation` | Don't show the "are you sure" exit dialog. | +| `--always-approve` / `--yolo` | Auto-approve every action (default in `--headless`). | +| `--llm-approve` | LLM-based security gate (interactive only — does NOT work in headless). | +| `--version` / `-v` | Print version and exit. | + +**There is no `--model`, `--max-iterations`, `--workspace`, `--sandbox`, `--sandbox-type` flag.** Model is `LLM_MODEL`. Workspace is the `workdir` you pass to the `terminal` tool. Sandbox / runtime is the `RUNTIME` and `SANDBOX_VOLUMES` env vars. + +## JSON Event Schema + +With `--json --headless`, OpenHands emits JSONL — one JSON object per line, plus a handful of non-JSON status lines (`Initializing agent...`, `Agent is working`, `Agent finished`, the final summary box, `Goodbye!`, `Conversation ID:`, `Hint:`). Filter for lines starting with `{`. + +Top-level `kind` field discriminates events: + +- `MessageEvent` — user / agent text turn. `source` is `user` or `agent`. +- `ActionEvent` — agent picked a tool. Read `tool_name` (`file_editor`, `terminal`, `finish`) and `action.kind` (`FileEditorAction`, `TerminalAction`, `FinishAction`). +- `ObservationEvent` — tool result. `observation.is_error` is the success flag. `source` is `environment`. +- `FinishAction` inside an `ActionEvent` carries the agent's final message in `action.message`. + +The cli prints all stderr from LiteLLM/Authlib first — see Pitfalls. Parse only stdout, line by line, ignoring lines that don't start with `{`. + +## Pitfalls + +- **LiteLLM warnings on every invocation.** The CLI prints `bedrock-runtime` and `sagemaker-runtime` warnings to stderr because `botocore` isn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to `/dev/null` or filter it out before showing the user. +- **Banner spam.** Without `OPENHANDS_SUPPRESS_BANNER=1`, every run starts with a multi-line `+--+` ASCII box advertising the SDK. Always export it. +- **`--override-with-envs` is mandatory for automation.** Without it, OpenHands ignores `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` and falls back to `~/.openhands/settings.json`. On a fresh install this file doesn't exist and the CLI hangs waiting for first-run setup. +- **Model slug is LiteLLM's, not the provider's.** `openrouter/openai/gpt-4o-mini` works; `openai/gpt-4o-mini` while pointed at OpenRouter does not. `anthropic/claude-sonnet-4-5` (hyphen) is native Anthropic; `openrouter/anthropic/claude-sonnet-4.5` (dot) is via OpenRouter. Get it wrong → cryptic LiteLLM 400. +- **`pip install openhands-ai` is the wrong package.** That's the legacy V0 SDK. The new CLI is `uv tool install openhands --python 3.12`. There is no maintained conda package. +- **Resume ID format is fiddly.** The CLI ends with `Conversation ID: f46573d9cfdb45e492ca189bde40019b` (no dashes) and then a `Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b` (with dashes). Use the dashed form. +- **Headless ignores `--llm-approve`.** If you pass it, you get an argparse error. Headless mode hardcodes always-approve. +- **No Windows support upstream.** The OpenHands docs require WSL on Windows. This skill is gated `[linux, macos]` accordingly. +- **`~/.openhands/conversations//` accumulates.** Each run persists a trajectory. Clean it up if running batches. +- **Heavy install (~200 packages).** Use `uv tool install` (isolated venv) to avoid dependency conflicts with the active project. + +## Verification + +``` +terminal( + command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Print the string OPENHANDS_OK to stdout via the terminal tool.'", + workdir="/tmp", + timeout=120 +) +``` + +If the JSONL stream ends with a `FinishAction` whose `action.message` mentions `OPENHANDS_OK`, the install is working. + +## Related + +- [OpenHands GitHub](https://github.com/All-Hands-AI/OpenHands) +- [OpenHands CLI command reference](https://docs.openhands.dev/openhands/usage/cli/command-reference) +- Sibling skills: `claude-code` (Anthropic-only), `codex` (OpenAI-only), `opencode` (multi-provider via OpenCode), `hermes-agent` (Hermes subagents via `delegate_task`). diff --git a/scripts/release.py b/scripts/release.py index 2211c911838..7b04827b724 100755 --- a/scripts/release.py +++ b/scripts/release.py @@ -87,6 +87,7 @@ AUTHOR_MAP = { "gaia@gaia.local": "jfuenmayor", "jiahuigu@users.noreply.github.com": "Jiahui-Gu", "openhands@all-hands.dev": "YLChen-007", + "3153586+xzessmedia@users.noreply.github.com": "xzessmedia", "AdamPlatin123@outlook.com": "AdamPlatin123", "32711803+waefrebeorn@users.noreply.github.com": "waefrebeorn", "32869278+dusterbloom@users.noreply.github.com": "dusterbloom", diff --git a/website/docs/reference/optional-skills-catalog.md b/website/docs/reference/optional-skills-catalog.md index bd2c22eff3c..e70f52fe32f 100644 --- a/website/docs/reference/optional-skills-catalog.md +++ b/website/docs/reference/optional-skills-catalog.md @@ -33,6 +33,7 @@ hermes skills uninstall |-------|-------------| | [**blackbox**](/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox) | Delegate coding tasks to Blackbox AI CLI agent. Multi-model agent with built-in judge that runs tasks through multiple LLMs and picks the best result. Requires the blackbox CLI and a Blackbox AI API key. | | [**honcho**](/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho) | Configure and use Honcho memory with Hermes -- cross-session user modeling, multi-profile peer isolation, observation config, dialectic reasoning, session summaries, and context budget enforcement. Use when setting up Honcho, troubleshoo... | +| [**openhands**](/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands) | Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). | ## blockchain diff --git a/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md new file mode 100644 index 00000000000..0e74f2573aa --- /dev/null +++ b/website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands.md @@ -0,0 +1,167 @@ +--- +title: "Openhands — Delegate coding to OpenHands CLI (model-agnostic, LiteLLM)" +sidebar_label: "Openhands" +description: "Delegate coding to OpenHands CLI (model-agnostic, LiteLLM)" +--- + +{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */} + +# Openhands + +Delegate coding to OpenHands CLI (model-agnostic, LiteLLM). + +## Skill metadata + +| | | +|---|---| +| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/openhands` | +| Path | `optional-skills/autonomous-ai-agents/openhands` | +| Version | `0.1.0` | +| Author | Tim Koepsel (xzessmedia), Hermes Agent | +| License | MIT | +| Platforms | linux, macos | +| Tags | `Coding-Agent`, `OpenHands`, `Model-Agnostic`, `LiteLLM` | +| Related skills | [`claude-code`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) | + +## Reference: full SKILL.md + +:::info +The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. +::: + +# OpenHands CLI + +Delegate coding tasks to the [OpenHands CLI](https://github.com/All-Hands-AI/OpenHands) via the `terminal` tool. OpenHands is model-agnostic: any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM, etc.). + +This skill is the headless-mode wrapper for batch / one-shot delegation. The interactive textual UI is not used from Hermes. + +## When to Use + +- User wants a coding task delegated to OpenHands specifically. +- User wants a coding agent that can run on a non-Anthropic / non-OpenAI provider (DeepSeek, Qwen, Ollama, vLLM, Nous, etc.) — sibling skills `claude-code` and `codex` are tied to one vendor. +- Multi-step file edits + shell commands inside a workspace. + +For Claude-native, prefer `claude-code`. For OpenAI-native, prefer `codex`. For Hermes-native subagents, use `delegate_task`. + +## Prerequisites + +1. Install upstream (requires Python 3.12+ and `uv`): + + ``` + terminal(command="uv tool install openhands --python 3.12") + ``` + + Verify: `openhands --version` (currently `OpenHands CLI 1.16.0` / `SDK v1.21.0` at time of writing). + +2. Pick a model and set env vars for `--override-with-envs`: + + ``` + export LLM_MODEL=openrouter/openai/gpt-4o-mini # or any LiteLLM slug + export LLM_API_KEY=$OPENROUTER_API_KEY + export LLM_BASE_URL=https://openrouter.ai/api/v1 # omit for native OpenAI + ``` + + `LLM_MODEL` uses LiteLLM's full slug. When the provider is OpenRouter the slug is doubly-prefixed: `openrouter//` (e.g. `openrouter/anthropic/claude-sonnet-4.5`). For native Anthropic: `anthropic/claude-sonnet-4-5`. For native OpenAI: `openai/gpt-4o-mini`. + +3. Suppress the startup banner so JSON output isn't preceded by ASCII art: + + ``` + export OPENHANDS_SUPPRESS_BANNER=1 + ``` + +## How to Run + +Always invoke through the `terminal` tool. Always pass `--headless --json --override-with-envs --exit-without-confirmation` for automation. + +### One-shot task + +``` +terminal( + command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'", + workdir="/path/to/project", + timeout=600 +) +``` + +### Background for long tasks + +``` +terminal(command="", workdir="/path/to/project", background=true, notify_on_complete=true) +process(action="poll", session_id="") +process(action="log", session_id="") +``` + +### Resume a previous conversation + +OpenHands prints `Conversation ID: <32-hex>` and a `Hint: openhands --resume ` line at the end of each run. Use the dashed form to resume: + +``` +terminal( + command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume -t 'Now fix the bug you found'", + workdir="/path/to/project" +) +``` + +## Real Flag List + +Verified against `openhands --help` (CLI 1.16.0). Anything not in this table is not a flag — pass it via env var or settings file. + +| Flag | Effect | +|------|--------| +| `--headless` | No UI, requires `-t` or `-f`. Auto-approves all actions (no `--llm-approve` in this mode). | +| `--json` | JSONL event stream (requires `--headless`). | +| `-t TEXT` | Task prompt. | +| `-f PATH` | Read task from file. | +| `--resume [ID]` | Resume conversation. No ID → list recent. | +| `--last` | Resume most recent (with `--resume`). | +| `--override-with-envs` | Apply `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` env vars. Without this, OpenHands uses `~/.openhands/settings.json` and ignores the env. | +| `--exit-without-confirmation` | Don't show the "are you sure" exit dialog. | +| `--always-approve` / `--yolo` | Auto-approve every action (default in `--headless`). | +| `--llm-approve` | LLM-based security gate (interactive only — does NOT work in headless). | +| `--version` / `-v` | Print version and exit. | + +**There is no `--model`, `--max-iterations`, `--workspace`, `--sandbox`, `--sandbox-type` flag.** Model is `LLM_MODEL`. Workspace is the `workdir` you pass to the `terminal` tool. Sandbox / runtime is the `RUNTIME` and `SANDBOX_VOLUMES` env vars. + +## JSON Event Schema + +With `--json --headless`, OpenHands emits JSONL — one JSON object per line, plus a handful of non-JSON status lines (`Initializing agent...`, `Agent is working`, `Agent finished`, the final summary box, `Goodbye!`, `Conversation ID:`, `Hint:`). Filter for lines starting with `{`. + +Top-level `kind` field discriminates events: + +- `MessageEvent` — user / agent text turn. `source` is `user` or `agent`. +- `ActionEvent` — agent picked a tool. Read `tool_name` (`file_editor`, `terminal`, `finish`) and `action.kind` (`FileEditorAction`, `TerminalAction`, `FinishAction`). +- `ObservationEvent` — tool result. `observation.is_error` is the success flag. `source` is `environment`. +- `FinishAction` inside an `ActionEvent` carries the agent's final message in `action.message`. + +The cli prints all stderr from LiteLLM/Authlib first — see Pitfalls. Parse only stdout, line by line, ignoring lines that don't start with `{`. + +## Pitfalls + +- **LiteLLM warnings on every invocation.** The CLI prints `bedrock-runtime` and `sagemaker-runtime` warnings to stderr because `botocore` isn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to `/dev/null` or filter it out before showing the user. +- **Banner spam.** Without `OPENHANDS_SUPPRESS_BANNER=1`, every run starts with a multi-line `+--+` ASCII box advertising the SDK. Always export it. +- **`--override-with-envs` is mandatory for automation.** Without it, OpenHands ignores `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` and falls back to `~/.openhands/settings.json`. On a fresh install this file doesn't exist and the CLI hangs waiting for first-run setup. +- **Model slug is LiteLLM's, not the provider's.** `openrouter/openai/gpt-4o-mini` works; `openai/gpt-4o-mini` while pointed at OpenRouter does not. `anthropic/claude-sonnet-4-5` (hyphen) is native Anthropic; `openrouter/anthropic/claude-sonnet-4.5` (dot) is via OpenRouter. Get it wrong → cryptic LiteLLM 400. +- **`pip install openhands-ai` is the wrong package.** That's the legacy V0 SDK. The new CLI is `uv tool install openhands --python 3.12`. There is no maintained conda package. +- **Resume ID format is fiddly.** The CLI ends with `Conversation ID: f46573d9cfdb45e492ca189bde40019b` (no dashes) and then a `Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b` (with dashes). Use the dashed form. +- **Headless ignores `--llm-approve`.** If you pass it, you get an argparse error. Headless mode hardcodes always-approve. +- **No Windows support upstream.** The OpenHands docs require WSL on Windows. This skill is gated `[linux, macos]` accordingly. +- **`~/.openhands/conversations//` accumulates.** Each run persists a trajectory. Clean it up if running batches. +- **Heavy install (~200 packages).** Use `uv tool install` (isolated venv) to avoid dependency conflicts with the active project. + +## Verification + +``` +terminal( + command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Print the string OPENHANDS_OK to stdout via the terminal tool.'", + workdir="/tmp", + timeout=120 +) +``` + +If the JSONL stream ends with a `FinishAction` whose `action.message` mentions `OPENHANDS_OK`, the install is working. + +## Related + +- [OpenHands GitHub](https://github.com/All-Hands-AI/OpenHands) +- [OpenHands CLI command reference](https://docs.openhands.dev/openhands/usage/cli/command-reference) +- Sibling skills: `claude-code` (Anthropic-only), `codex` (OpenAI-only), `opencode` (multi-provider via OpenCode), `hermes-agent` (Hermes subagents via `delegate_task`). diff --git a/website/sidebars.ts b/website/sidebars.ts index a3c41cbf205..a994e4e7fee 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -392,6 +392,7 @@ const sidebars: SidebarsConfig = { items: [ 'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-blackbox', 'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho', + 'user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-openhands', ], }, {