From 74b3d400d5c8596dd0a8a1ca3decc4c14fa7d022 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 09:47:36 +0000 Subject: [PATCH 1/7] docs: Add section on launching one-off tasks via Cloud API Added a new section to the cloud-workspace guide explaining how to use the OpenHands Cloud API directly for launching asynchronous tasks. This is useful for CI/CD workflows where you want to start a task and exit immediately. Key additions: - Introduction updated to mention both approaches (OpenHandsCloudWorkspace vs Cloud API Direct) - New 'Launching One-Off Tasks via Cloud API' section with: - Comparison table of both approaches - Explanation of how Cloud API uses account-configured LLM and GitHub credentials - Python code example showing how to start a conversation via the API - GitHub Actions example using the PR Review workflow - Decision guide for when to use each approach - Added link to PR Review workflow in Next Steps This documents the cloud mode feature added in PR #1966 of software-agent-sdk. Co-authored-by: openhands --- sdk/guides/agent-server/cloud-workspace.mdx | 134 +++++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index cf4164d2..91eadcd9 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -5,7 +5,12 @@ description: Connect to OpenHands Cloud for fully managed sandbox environments. > A ready-to-run example is available [here](#ready-to-run-example)! -The `OpenHandsCloudWorkspace` demonstrates how to use the [OpenHands Cloud](https://app.all-hands.dev) to provision and manage sandboxed environments for agent execution. This provides a seamless experience with automatic sandbox provisioning, monitoring, and secure execution without managing your own infrastructure. +The [OpenHands Cloud](https://app.all-hands.dev) provides fully managed sandbox environments for agent execution. There are two ways to use it: + +1. **OpenHandsCloudWorkspace** - SDK integration for running agents with your own LLM configuration +2. **Cloud API Direct** - Launch one-off tasks that use your cloud-configured LLM and credentials + +This guide covers both approaches. ## Key Concepts @@ -206,9 +211,136 @@ cd agent-sdk uv run python examples/02_remote_agent_server/07_convo_with_cloud_workspace.py ``` +## Launching One-Off Tasks via Cloud API + +For scenarios where you want to launch a task and let it run asynchronously in the cloud (without waiting for completion), you can use the OpenHands Cloud API directly. This is particularly useful for: + +- **CI/CD workflows** - Trigger code reviews or automated tasks without blocking pipelines +- **Background processing** - Launch long-running tasks and check results later +- **Minimal configuration** - Only need an API key; LLM and GitHub credentials come from your cloud account + +### Key Benefits + +| Aspect | OpenHandsCloudWorkspace | Cloud API Direct | +|--------|------------------------|------------------| +| LLM Configuration | You provide `LLM_API_KEY` | Uses your cloud-configured LLM | +| GitHub Access | You provide `GITHUB_TOKEN` | Uses your cloud-configured credentials | +| Execution Model | Blocking (waits for completion) | Non-blocking (fire and forget) | +| Best For | Interactive scripts, testing | CI/CD, automated workflows | + +### How It Works + +The Cloud API creates a conversation that: +1. Uses your account's configured LLM (no API key needed in the request) +2. Has access to your GitHub credentials (if configured in your cloud account) +3. Runs asynchronously - you get a conversation URL to track progress +4. Can be viewed in the OpenHands Cloud UI + +### Example: PR Review Workflow + +This example from the [PR Review GitHub Action](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) demonstrates launching a code review task via the Cloud API: + +```python icon="python" +import json +import urllib.request + +def start_cloud_conversation( + cloud_api_url: str, + cloud_api_key: str, + initial_message: str, +) -> tuple[str, str]: + """Start a conversation via OpenHands Cloud API. + + This creates a conversation directly through the Cloud API, which: + - Uses the user's cloud-configured LLM (no LLM credentials needed) + - Uses the user's cloud-configured GitHub credentials + - Provisions a sandbox automatically + - Returns a conversation URL for tracking in the UI + + Args: + cloud_api_url: OpenHands Cloud API URL (e.g., https://app.all-hands.dev) + cloud_api_key: API key for OpenHands Cloud + initial_message: The initial prompt to send to the agent + + Returns: + Tuple of (conversation_id, conversation_url) + """ + url = f"{cloud_api_url}/api/conversations" + + payload = {"initial_user_msg": initial_message} + + data = json.dumps(payload).encode("utf-8") + request = urllib.request.Request(url, data=data, method="POST") + request.add_header("Authorization", f"Bearer {cloud_api_key}") + request.add_header("Content-Type", "application/json") + + with urllib.request.urlopen(request, timeout=120) as response: + result = json.loads(response.read().decode("utf-8")) + + conversation_id = result.get("conversation_id") + conversation_url = f"{cloud_api_url}/conversations/{conversation_id}" + return conversation_id, conversation_url + + +# Example usage for PR review +prompt = """ +Review the PR and identify issues that need to be addressed. + +## Pull Request Information +- **Repository**: OpenHands/software-agent-sdk +- **PR Number**: 1234 +- **Title**: Add new feature + +## Instructions +1. Fetch the PR diff using: gh pr diff 1234 --repo OpenHands/software-agent-sdk +2. Analyze the changes thoroughly +3. Post your review using the GitHub API (GITHUB_TOKEN is available) +""" + +conversation_id, conversation_url = start_cloud_conversation( + cloud_api_url="https://app.all-hands.dev", + cloud_api_key="your-api-key", + initial_message=prompt, +) + +print(f"Review started: {conversation_url}") +# The workflow can exit immediately - review continues in the cloud +``` + +### Using in GitHub Actions + +The PR Review workflow demonstrates a complete implementation: + +```yaml icon="yaml" +- name: Run PR Review (Cloud Mode) + uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + with: + mode: cloud + review-style: roasted + # Only the cloud API key is needed - LLM and GitHub access + # come from your OpenHands Cloud account configuration + openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} +``` + + +See the full PR Review example: [examples/03_github_workflows/02_pr_review](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) + + +### When to Use Each Approach + +| Use Case | Recommended Approach | +|----------|---------------------| +| Interactive development | `OpenHandsCloudWorkspace` | +| Unit tests with cloud sandbox | `OpenHandsCloudWorkspace` | +| CI/CD code reviews | Cloud API Direct | +| Background automation | Cloud API Direct | +| Need custom LLM config | `OpenHandsCloudWorkspace` | +| Want simplest setup | Cloud API Direct | + ## Next Steps - **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service - **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run locally with Docker - **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers - **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details +- **[PR Review Workflow](/sdk/guides/github-workflows/pr-review)** - Complete GitHub Actions example From b6d7774a2505b0c865ffa22f4d33cb11bcece1dc Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 09:52:06 +0000 Subject: [PATCH 2/7] docs: Add cloud mode documentation to PR review guides Updated both PR review documentation pages to include the new cloud mode option: 1. sdk/guides/github-workflows/pr-review.mdx: - Added 'Review Modes' section explaining SDK vs Cloud modes - Added tabs in Quick Start for SDK and Cloud mode setup - Updated Action Inputs table with cloud mode options - Added Cloud Mode Workflow Example with complete YAML 2. openhands/usage/use-cases/code-review.mdx: - Added 'Review Modes' section with comparison table - Added 'Cloud Mode Benefits' subsection - Added tabs in Quick Start for SDK and Cloud mode workflows - Updated Action Inputs table with cloud mode options - Added link to Cloud Workspace Guide in Related Resources Cloud mode benefits: - Only needs OPENHANDS_CLOUD_API_KEY (no LLM_API_KEY or GITHUB_TOKEN) - Uses cloud-configured LLM and GitHub credentials - Workflow exits immediately; review runs asynchronously - Track progress via conversation URL in OpenHands Cloud UI Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 207 ++++++++++++++++------ sdk/guides/github-workflows/pr-review.mdx | 110 ++++++++++-- 2 files changed, 245 insertions(+), 72 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 65a25504..582d3fe7 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -13,6 +13,24 @@ The OpenHands PR Review workflow is a GitHub Actions workflow that: - **Analyzes code changes** in the context of your entire repository - **Posts inline comments** directly on specific lines of code in the PR - **Provides fast feedback** - typically within 2-3 minutes +- **Supports two modes** - SDK (local) or Cloud (asynchronous) + +## Review Modes + +The workflow supports two execution modes: + +| Mode | Description | Required Secrets | Best For | +|------|-------------|-----------------|----------| +| **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | Full control over LLM configuration | +| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY` only | Simplest setup, faster CI | + +### Cloud Mode Benefits + +- **Minimal configuration** - Only one secret needed (`OPENHANDS_CLOUD_API_KEY`) +- **No LLM setup** - Uses your OpenHands Cloud account's configured LLM +- **No GITHUB_TOKEN needed** - Agent uses your cloud-configured GitHub credentials +- **Faster CI completion** - Workflow exits immediately; review runs in background +- **Track progress** - View the conversation in the [OpenHands Cloud UI](https://app.all-hands.dev) ## How It Works @@ -44,60 +62,125 @@ Choose between two review styles: ## Quick Start - - - Create `.github/workflows/pr-review-by-openhands.yml` in your repository: - - ```yaml - name: PR Review by OpenHands - - on: - pull_request_target: - types: [opened, ready_for_review, labeled, review_requested] - - permissions: - contents: read - pull-requests: write - issues: write - - jobs: - pr-review: - if: | - (github.event.action == 'opened' && github.event.pull_request.draft == false) || - github.event.action == 'ready_for_review' || - github.event.label.name == 'review-this' || - github.event.requested_reviewer.login == 'openhands-agent' - runs-on: ubuntu-latest - steps: - - name: Run PR Review - uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main - with: - llm-model: anthropic/claude-sonnet-4-5-20250929 - review-style: standard - llm-api-key: ${{ secrets.LLM_API_KEY }} - github-token: ${{ secrets.GITHUB_TOKEN }} - ``` - - - - Go to your repository's **Settings → Secrets and variables → Actions** and add: - - **`LLM_API_KEY`**: Your LLM API key (get one from [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms)) - - - - Create a `review-this` label in your repository: - 1. Go to **Issues → Labels** - 2. Click **New label** - 3. Name: `review-this` - 4. Description: `Trigger OpenHands PR review` - - - - Open a PR and either: - - Add the `review-this` label, OR - - Request `openhands-agent` as a reviewer - - + + + + + Create `.github/workflows/pr-review-by-openhands.yml` in your repository: + + ```yaml + name: PR Review by OpenHands + + on: + pull_request_target: + types: [opened, ready_for_review, labeled, review_requested] + + permissions: + contents: read + pull-requests: write + issues: write + + jobs: + pr-review: + if: | + (github.event.action == 'opened' && github.event.pull_request.draft == false) || + github.event.action == 'ready_for_review' || + github.event.label.name == 'review-this' || + github.event.requested_reviewer.login == 'openhands-agent' + runs-on: ubuntu-latest + steps: + - name: Run PR Review + uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + with: + llm-model: anthropic/claude-sonnet-4-5-20250929 + review-style: standard + llm-api-key: ${{ secrets.LLM_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} + ``` + + + + Go to your repository's **Settings → Secrets and variables → Actions** and add: + - **`LLM_API_KEY`**: Your LLM API key (get one from [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms)) + + + + Create a `review-this` label in your repository: + 1. Go to **Issues → Labels** + 2. Click **New label** + 3. Name: `review-this` + 4. Description: `Trigger OpenHands PR review` + + + + Open a PR and either: + - Add the `review-this` label, OR + - Request `openhands-agent` as a reviewer + + + + + + + Create `.github/workflows/pr-review-by-openhands.yml` in your repository: + + ```yaml + name: PR Review by OpenHands (Cloud) + + on: + pull_request_target: + types: [opened, ready_for_review, labeled, review_requested] + + permissions: + contents: read + pull-requests: write + issues: write + + jobs: + pr-review: + if: | + (github.event.action == 'opened' && github.event.pull_request.draft == false) || + github.event.action == 'ready_for_review' || + github.event.label.name == 'review-this' || + github.event.requested_reviewer.login == 'openhands-agent' + runs-on: ubuntu-latest + steps: + - name: Run PR Review + uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main + with: + mode: cloud + review-style: standard + openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + ``` + + + + Go to your repository's **Settings → Secrets and variables → Actions** and add: + - **`OPENHANDS_CLOUD_API_KEY`**: Get one from [OpenHands Cloud Settings](https://app.all-hands.dev/settings/api-keys) + + + Make sure you have an LLM configured in your [OpenHands Cloud account](https://app.all-hands.dev) and have connected your GitHub account. + + + + + Create a `review-this` label in your repository: + 1. Go to **Issues → Labels** + 2. Click **New label** + 3. Name: `review-this` + 4. Description: `Trigger OpenHands PR review` + + + + Open a PR and either: + - Add the `review-this` label, OR + - Request `openhands-agent` as a reviewer + + The workflow will exit immediately, and you can track the review progress in the [OpenHands Cloud UI](https://app.all-hands.dev). The conversation URL is printed in the workflow logs. + + + + ## Composite Action @@ -112,18 +195,25 @@ The workflow uses a reusable composite action from the Software Agent SDK that h | Input | Description | Required | Default | |-------|-------------|----------|---------| -| `llm-model` | LLM model to use | Yes | - | -| `llm-base-url` | LLM base URL (for custom endpoints) | No | `''` | +| `mode` | Review mode: `sdk` or `cloud` | No | `sdk` | +| `llm-model` | LLM model (SDK mode only) | SDK mode | `anthropic/claude-sonnet-4-5-20250929` | +| `llm-base-url` | LLM base URL (SDK mode only) | No | `''` | | `review-style` | Review style: `standard` or `roasted` | No | `roasted` | | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | -| `llm-api-key` | LLM API key | Yes | - | -| `github-token` | GitHub token for API access | Yes | - | +| `llm-api-key` | LLM API key (SDK mode only) | SDK mode | - | +| `github-token` | GitHub token (SDK mode only) | SDK mode | - | +| `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | Cloud mode | - | +| `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` | Use `sdk-version` to pin to a specific version tag (e.g., `v1.0.0`) for production stability, or use `main` to always get the latest features. + +In **cloud mode**, the workflow creates a conversation in OpenHands Cloud and exits immediately. The agent runs asynchronously using your cloud-configured LLM and GitHub credentials. Track progress via the conversation URL printed in the logs. + + ## Customization ### Repository-Specific Review Guidelines @@ -262,6 +352,7 @@ See real automated reviews in action on the OpenHands Software Agent SDK reposit - [PR Review Workflow Reference](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) - Full workflow example and agent script - [Composite Action](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/actions/pr-review/action.yml) - Reusable GitHub Action for PR reviews +- [Cloud Workspace Guide](/sdk/guides/agent-server/cloud-workspace) - Learn about launching one-off tasks via Cloud API - [Software Agent SDK](/sdk/index) - Build your own AI-powered workflows - [GitHub Integration](/openhands/usage/cloud/github-installation) - Set up GitHub integration for OpenHands Cloud - [Skills Documentation](/overview/skills) - Learn more about OpenHands skills diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index 9dfb5820..c1410b10 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -13,19 +13,54 @@ Automatically review pull requests, providing feedback on code quality, security The reference workflow triggers on either the "review-this" label or when the openhands-agent account is requested as a reviewer. In OpenHands organization repositories, openhands-agent has access, so this works as-is. In your own repositories, requesting openhands-agent will only work if that account is added as a collaborator or is part of a team with access. If you don't plan to grant access, use the label trigger instead, or change the condition to a reviewer handle that exists in your repo. +## Review Modes + +The PR review workflow supports two modes: + +| Mode | Description | Required Secrets | +|------|-------------|-----------------| +| **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | +| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY` only | + +### Cloud Mode Benefits + +- **Minimal configuration** - Only one secret needed +- **No LLM setup** - Uses your OpenHands Cloud account's configured LLM +- **No GITHUB_TOKEN needed** - Agent uses your cloud-configured GitHub credentials +- **Faster CI completion** - Workflow exits immediately; review runs in background +- **Track progress** - View the conversation in the OpenHands Cloud UI + ## Quick Start -```bash -# 1. Copy workflow to your repository -cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml + + + ```bash + # 1. Copy workflow to your repository + cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml -# 2. Configure secrets in GitHub Settings → Secrets -# Add: LLM_API_KEY + # 2. Configure secrets in GitHub Settings → Secrets + # Add: LLM_API_KEY -# 3. (Optional) Create a "review-this" label in your repository -# Go to Issues → Labels → New label -# You can also trigger reviews by requesting "openhands-agent" as a reviewer -``` + # 3. (Optional) Create a "review-this" label in your repository + # Go to Issues → Labels → New label + # You can also trigger reviews by requesting "openhands-agent" as a reviewer + ``` + + + ```bash + # 1. Copy workflow to your repository + cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml + + # 2. Configure secrets in GitHub Settings → Secrets + # Add: OPENHANDS_CLOUD_API_KEY (get from https://app.all-hands.dev/settings/api-keys) + + # 3. Update the workflow to use cloud mode: + # Set mode: cloud and remove llm-api-key and github-token + + # 4. (Optional) Create a "review-this" label in your repository + ``` + + ## Features @@ -33,6 +68,7 @@ cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-r - **Comprehensive Analysis** - Analyzes the changes given the repository context. Covers code quality, security, best practices - **GitHub Integration** - Posts comments directly to the PR - **Customizable** - Add your own code review guidelines without forking +- **Two Modes** - Run locally (SDK) or in the cloud (asynchronous) ## Security @@ -161,13 +197,59 @@ jobs: | Input | Description | Required | Default | |-------|-------------|----------|---------| -| `llm-model` | LLM model to use | Yes | - | -| `llm-base-url` | LLM base URL (optional) | No | `''` | -| `review-style` | Review style: 'standard' or 'roasted' | No | `roasted` | +| `mode` | Review mode: `sdk` or `cloud` | No | `sdk` | +| `llm-model` | LLM model (SDK mode only) | SDK mode | `anthropic/claude-sonnet-4-5-20250929` | +| `llm-base-url` | LLM base URL (SDK mode only) | No | `''` | +| `review-style` | Review style: `standard` or `roasted` | No | `roasted` | | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | -| `llm-api-key` | LLM API key | Yes | - | -| `github-token` | GitHub token for API access | Yes | - | +| `llm-api-key` | LLM API key (SDK mode only) | SDK mode | - | +| `github-token` | GitHub token (SDK mode only) | SDK mode | - | +| `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | Cloud mode | - | +| `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` | + +### Cloud Mode Workflow Example + +For cloud mode, the workflow is simpler since you only need the cloud API key: + +```yaml icon="yaml" +name: PR Review by OpenHands (Cloud Mode) + +on: + pull_request: + types: [labeled, review_requested] + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + pr-review: + if: | + github.event.label.name == 'review-this' || + github.event.requested_reviewer.login == 'openhands-agent' + runs-on: ubuntu-latest + steps: + - name: Checkout for composite action + uses: actions/checkout@v4 + with: + repository: OpenHands/software-agent-sdk + ref: main + sparse-checkout: .github/actions/pr-review + + - name: Run PR Review + uses: ./.github/actions/pr-review + with: + mode: cloud + review-style: roasted + # Only the cloud API key is needed + openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} +``` + + +In cloud mode, the workflow exits immediately after starting the review. The agent runs asynchronously in OpenHands Cloud and posts review comments when done. You can track progress via the conversation URL printed in the workflow logs. + ## Related Files From e27cd86e44d4482783ef011a11c0e4998bfa5b6c Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 09:54:07 +0000 Subject: [PATCH 3/7] docs: Update API key references to point to cloud-api docs Updated all references to getting an OpenHands Cloud API key to point to the official documentation page: /openhands/usage/cloud/cloud-api#obtaining-an-api-key This provides a single source of truth for API key instructions. Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 2 +- sdk/guides/agent-server/cloud-workspace.mdx | 7 +------ sdk/guides/github-workflows/pr-review.mdx | 2 +- 3 files changed, 3 insertions(+), 8 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 582d3fe7..b444eb1b 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -156,7 +156,7 @@ Choose between two review styles: Go to your repository's **Settings → Secrets and variables → Actions** and add: - - **`OPENHANDS_CLOUD_API_KEY`**: Get one from [OpenHands Cloud Settings](https://app.all-hands.dev/settings/api-keys) + - **`OPENHANDS_CLOUD_API_KEY`**: See [Obtaining an API Key](/openhands/usage/cloud/cloud-api#obtaining-an-api-key) Make sure you have an LLM configured in your [OpenHands Cloud account](https://app.all-hands.dev) and have connected your GitHub account. diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index 91eadcd9..8cf7ec90 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -33,12 +33,7 @@ This workspace type: ### Getting Your API Key -To use OpenHands Cloud, you need an API key: - -1. Go to [app.all-hands.dev](https://app.all-hands.dev) -2. Sign in to your account -3. Navigate to Settings → API Keys -4. Create a new API key +To use OpenHands Cloud, you need an API key. See [Obtaining an API Key](/openhands/usage/cloud/cloud-api#obtaining-an-api-key) for detailed instructions. Store this key securely and use it as the `OPENHANDS_CLOUD_API_KEY` environment variable. diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index c1410b10..14123261 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -52,7 +52,7 @@ The PR review workflow supports two modes: cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml # 2. Configure secrets in GitHub Settings → Secrets - # Add: OPENHANDS_CLOUD_API_KEY (get from https://app.all-hands.dev/settings/api-keys) + # Add: OPENHANDS_CLOUD_API_KEY (see https://docs.openhands.dev/openhands/usage/cloud/cloud-api#obtaining-an-api-key) # 3. Update the workflow to use cloud mode: # Set mode: cloud and remove llm-api-key and github-token From e44c62655d1600978a1f1671c8262263c89610d3 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 10:20:49 +0000 Subject: [PATCH 4/7] fix: Update docs - GITHUB_TOKEN required for both modes Cloud mode needs GITHUB_TOKEN to post initial comment with conversation URL. Changes: - Updated Review Modes tables to show GITHUB_TOKEN required for both - Updated cloud mode workflow examples to include github-token - Updated Action Inputs tables Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 13 ++++++------- sdk/guides/github-workflows/pr-review.mdx | 17 ++++++++--------- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index b444eb1b..0cf90d57 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -22,15 +22,13 @@ The workflow supports two execution modes: | Mode | Description | Required Secrets | Best For | |------|-------------|-----------------|----------| | **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | Full control over LLM configuration | -| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY` only | Simplest setup, faster CI | +| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN` | No LLM setup, faster CI | ### Cloud Mode Benefits -- **Minimal configuration** - Only one secret needed (`OPENHANDS_CLOUD_API_KEY`) - **No LLM setup** - Uses your OpenHands Cloud account's configured LLM -- **No GITHUB_TOKEN needed** - Agent uses your cloud-configured GitHub credentials - **Faster CI completion** - Workflow exits immediately; review runs in background -- **Track progress** - View the conversation in the [OpenHands Cloud UI](https://app.all-hands.dev) +- **Track progress** - Posts a comment on the PR with a link to the conversation URL ## How It Works @@ -151,6 +149,7 @@ Choose between two review styles: mode: cloud review-style: standard openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` @@ -176,7 +175,7 @@ Choose between two review styles: - Add the `review-this` label, OR - Request `openhands-agent` as a reviewer - The workflow will exit immediately, and you can track the review progress in the [OpenHands Cloud UI](https://app.all-hands.dev). The conversation URL is printed in the workflow logs. + The workflow posts a comment with a link to track progress, then exits. The agent runs asynchronously in the cloud. @@ -202,7 +201,7 @@ The workflow uses a reusable composite action from the Software Agent SDK that h | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | | `llm-api-key` | LLM API key (SDK mode only) | SDK mode | - | -| `github-token` | GitHub token (SDK mode only) | SDK mode | - | +| `github-token` | GitHub token for API access | Yes | - | | `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | Cloud mode | - | | `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` | @@ -211,7 +210,7 @@ Use `sdk-version` to pin to a specific version tag (e.g., `v1.0.0`) for producti -In **cloud mode**, the workflow creates a conversation in OpenHands Cloud and exits immediately. The agent runs asynchronously using your cloud-configured LLM and GitHub credentials. Track progress via the conversation URL printed in the logs. +In **cloud mode**, the workflow posts a comment with a link to track progress, then exits immediately. The agent runs asynchronously in OpenHands Cloud using your configured LLM. ## Customization diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index 14123261..3e090525 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -20,15 +20,13 @@ The PR review workflow supports two modes: | Mode | Description | Required Secrets | |------|-------------|-----------------| | **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | -| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY` only | +| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN` | ### Cloud Mode Benefits -- **Minimal configuration** - Only one secret needed - **No LLM setup** - Uses your OpenHands Cloud account's configured LLM -- **No GITHUB_TOKEN needed** - Agent uses your cloud-configured GitHub credentials - **Faster CI completion** - Workflow exits immediately; review runs in background -- **Track progress** - View the conversation in the OpenHands Cloud UI +- **Track progress** - Posts a comment on the PR with a link to the conversation URL ## Quick Start @@ -53,9 +51,10 @@ The PR review workflow supports two modes: # 2. Configure secrets in GitHub Settings → Secrets # Add: OPENHANDS_CLOUD_API_KEY (see https://docs.openhands.dev/openhands/usage/cloud/cloud-api#obtaining-an-api-key) + # GITHUB_TOKEN is auto-available in GitHub Actions # 3. Update the workflow to use cloud mode: - # Set mode: cloud and remove llm-api-key and github-token + # Set mode: cloud and remove llm-api-key # 4. (Optional) Create a "review-this" label in your repository ``` @@ -204,13 +203,13 @@ jobs: | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | | `llm-api-key` | LLM API key (SDK mode only) | SDK mode | - | -| `github-token` | GitHub token (SDK mode only) | SDK mode | - | +| `github-token` | GitHub token for API access | Yes | - | | `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | Cloud mode | - | | `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` | ### Cloud Mode Workflow Example -For cloud mode, the workflow is simpler since you only need the cloud API key: +For cloud mode, you don't need an LLM API key - just the cloud API key: ```yaml icon="yaml" name: PR Review by OpenHands (Cloud Mode) @@ -243,12 +242,12 @@ jobs: with: mode: cloud review-style: roasted - # Only the cloud API key is needed openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` -In cloud mode, the workflow exits immediately after starting the review. The agent runs asynchronously in OpenHands Cloud and posts review comments when done. You can track progress via the conversation URL printed in the workflow logs. +In cloud mode, the workflow posts a comment on the PR with a link to the conversation URL, then exits immediately. The agent runs asynchronously in OpenHands Cloud and posts review comments when done. ## Related Files From 13ac6f2e4122faabf8060fff87beab294caafaaf Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 10:24:47 +0000 Subject: [PATCH 5/7] docs: Add cloud mode prerequisites about GitHub access The OpenHands Cloud account must have GitHub access to the target repository. Added warning and link to GitHub Installation Guide in both PR review docs. Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 8 ++++++++ sdk/guides/github-workflows/pr-review.mdx | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 0cf90d57..07ff7d51 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -30,6 +30,14 @@ The workflow supports two execution modes: - **Faster CI completion** - Workflow exits immediately; review runs in background - **Track progress** - Posts a comment on the PR with a link to the conversation URL +### Cloud Mode Prerequisites + + +The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments. + +Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud. + + ## How It Works The PR review workflow uses the OpenHands Software Agent SDK to analyze your code changes: diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index 3e090525..efde8af7 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -28,6 +28,14 @@ The PR review workflow supports two modes: - **Faster CI completion** - Workflow exits immediately; review runs in background - **Track progress** - Posts a comment on the PR with a link to the conversation URL +### Cloud Mode Prerequisites + + +The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments. + +Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud. + + ## Quick Start From 0414c209678770fae6d1ad38ee6d337f17024231 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 11:06:41 +0000 Subject: [PATCH 6/7] docs: Update cloud mode to use OpenHandsCloudWorkspace Updated documentation to reflect the refactored cloud mode: - Both modes use the same Agent, LLM, and Conversation pattern - The only difference is the workspace type (local vs OpenHandsCloudWorkspace) - Both modes require LLM_API_KEY since LLM config is sent to cloud sandbox - Removed outdated 'Cloud API Direct' documentation Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 34 +++--- sdk/guides/agent-server/cloud-workspace.mdx | 123 ++------------------ sdk/guides/github-workflows/pr-review.mdx | 37 +++--- 3 files changed, 37 insertions(+), 157 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 07ff7d51..33afa250 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -21,22 +21,17 @@ The workflow supports two execution modes: | Mode | Description | Required Secrets | Best For | |------|-------------|-----------------|----------| -| **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | Full control over LLM configuration | -| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN` | No LLM setup, faster CI | +| **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | Local execution | +| **Cloud Mode** | Runs in an OpenHands Cloud sandbox | `LLM_API_KEY`, `GITHUB_TOKEN`, `OPENHANDS_CLOUD_API_KEY` | Managed infrastructure | -### Cloud Mode Benefits - -- **No LLM setup** - Uses your OpenHands Cloud account's configured LLM -- **Faster CI completion** - Workflow exits immediately; review runs in background -- **Track progress** - Posts a comment on the PR with a link to the conversation URL - -### Cloud Mode Prerequisites +Both modes use the same Agent, LLM, and Conversation pattern - the only difference is the workspace type: +- **SDK mode**: Uses local workspace +- **Cloud mode**: Uses `OpenHandsCloudWorkspace` for a managed cloud sandbox - -The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments. +### Cloud Mode Benefits -Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud. - +- **Managed infrastructure** - Runs in OpenHands Cloud sandbox +- **Same agent logic** - Uses exactly the same Agent and Conversation as SDK mode ## How It Works @@ -155,19 +150,18 @@ Choose between two review styles: uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main with: mode: cloud + llm-model: anthropic/claude-sonnet-4-5-20250929 review-style: standard - openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + llm-api-key: ${{ secrets.LLM_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} + openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} ``` - + Go to your repository's **Settings → Secrets and variables → Actions** and add: + - **`LLM_API_KEY`**: Your LLM API key (get one from [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms)) - **`OPENHANDS_CLOUD_API_KEY`**: See [Obtaining an API Key](/openhands/usage/cloud/cloud-api#obtaining-an-api-key) - - - Make sure you have an LLM configured in your [OpenHands Cloud account](https://app.all-hands.dev) and have connected your GitHub account. - @@ -182,8 +176,6 @@ Choose between two review styles: Open a PR and either: - Add the `review-this` label, OR - Request `openhands-agent` as a reviewer - - The workflow posts a comment with a link to track progress, then exits. The agent runs asynchronously in the cloud. diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index 8cf7ec90..a3b9e050 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -5,12 +5,9 @@ description: Connect to OpenHands Cloud for fully managed sandbox environments. > A ready-to-run example is available [here](#ready-to-run-example)! -The [OpenHands Cloud](https://app.all-hands.dev) provides fully managed sandbox environments for agent execution. There are two ways to use it: +The [OpenHands Cloud](https://app.all-hands.dev) provides fully managed sandbox environments for agent execution. -1. **OpenHandsCloudWorkspace** - SDK integration for running agents with your own LLM configuration -2. **Cloud API Direct** - Launch one-off tasks that use your cloud-configured LLM and credentials - -This guide covers both approaches. +The `OpenHandsCloudWorkspace` connects to OpenHands Cloud to provision sandboxes, allowing you to run agents with your own LLM configuration in a managed cloud environment. ## Key Concepts @@ -206,114 +203,19 @@ cd agent-sdk uv run python examples/02_remote_agent_server/07_convo_with_cloud_workspace.py ``` -## Launching One-Off Tasks via Cloud API - -For scenarios where you want to launch a task and let it run asynchronously in the cloud (without waiting for completion), you can use the OpenHands Cloud API directly. This is particularly useful for: - -- **CI/CD workflows** - Trigger code reviews or automated tasks without blocking pipelines -- **Background processing** - Launch long-running tasks and check results later -- **Minimal configuration** - Only need an API key; LLM and GitHub credentials come from your cloud account - -### Key Benefits - -| Aspect | OpenHandsCloudWorkspace | Cloud API Direct | -|--------|------------------------|------------------| -| LLM Configuration | You provide `LLM_API_KEY` | Uses your cloud-configured LLM | -| GitHub Access | You provide `GITHUB_TOKEN` | Uses your cloud-configured credentials | -| Execution Model | Blocking (waits for completion) | Non-blocking (fire and forget) | -| Best For | Interactive scripts, testing | CI/CD, automated workflows | - -### How It Works - -The Cloud API creates a conversation that: -1. Uses your account's configured LLM (no API key needed in the request) -2. Has access to your GitHub credentials (if configured in your cloud account) -3. Runs asynchronously - you get a conversation URL to track progress -4. Can be viewed in the OpenHands Cloud UI - -### Example: PR Review Workflow - -This example from the [PR Review GitHub Action](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) demonstrates launching a code review task via the Cloud API: - -```python icon="python" -import json -import urllib.request - -def start_cloud_conversation( - cloud_api_url: str, - cloud_api_key: str, - initial_message: str, -) -> tuple[str, str]: - """Start a conversation via OpenHands Cloud API. - - This creates a conversation directly through the Cloud API, which: - - Uses the user's cloud-configured LLM (no LLM credentials needed) - - Uses the user's cloud-configured GitHub credentials - - Provisions a sandbox automatically - - Returns a conversation URL for tracking in the UI - - Args: - cloud_api_url: OpenHands Cloud API URL (e.g., https://app.all-hands.dev) - cloud_api_key: API key for OpenHands Cloud - initial_message: The initial prompt to send to the agent - - Returns: - Tuple of (conversation_id, conversation_url) - """ - url = f"{cloud_api_url}/api/conversations" - - payload = {"initial_user_msg": initial_message} - - data = json.dumps(payload).encode("utf-8") - request = urllib.request.Request(url, data=data, method="POST") - request.add_header("Authorization", f"Bearer {cloud_api_key}") - request.add_header("Content-Type", "application/json") +## Using in GitHub Actions - with urllib.request.urlopen(request, timeout=120) as response: - result = json.loads(response.read().decode("utf-8")) - - conversation_id = result.get("conversation_id") - conversation_url = f"{cloud_api_url}/conversations/{conversation_id}" - return conversation_id, conversation_url - - -# Example usage for PR review -prompt = """ -Review the PR and identify issues that need to be addressed. - -## Pull Request Information -- **Repository**: OpenHands/software-agent-sdk -- **PR Number**: 1234 -- **Title**: Add new feature - -## Instructions -1. Fetch the PR diff using: gh pr diff 1234 --repo OpenHands/software-agent-sdk -2. Analyze the changes thoroughly -3. Post your review using the GitHub API (GITHUB_TOKEN is available) -""" - -conversation_id, conversation_url = start_cloud_conversation( - cloud_api_url="https://app.all-hands.dev", - cloud_api_key="your-api-key", - initial_message=prompt, -) - -print(f"Review started: {conversation_url}") -# The workflow can exit immediately - review continues in the cloud -``` - -### Using in GitHub Actions - -The PR Review workflow demonstrates a complete implementation: +The `OpenHandsCloudWorkspace` can be used in GitHub Actions for CI/CD workflows. See the [PR Review Workflow](/sdk/guides/github-workflows/pr-review) for a complete example that demonstrates running code reviews in cloud mode: ```yaml icon="yaml" - name: Run PR Review (Cloud Mode) uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main with: mode: cloud + llm-model: anthropic/claude-sonnet-4-5-20250929 review-style: roasted - # Only the cloud API key is needed - LLM and GitHub access - # come from your OpenHands Cloud account configuration + llm-api-key: ${{ secrets.LLM_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} ``` @@ -321,17 +223,6 @@ The PR Review workflow demonstrates a complete implementation: See the full PR Review example: [examples/03_github_workflows/02_pr_review](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) -### When to Use Each Approach - -| Use Case | Recommended Approach | -|----------|---------------------| -| Interactive development | `OpenHandsCloudWorkspace` | -| Unit tests with cloud sandbox | `OpenHandsCloudWorkspace` | -| CI/CD code reviews | Cloud API Direct | -| Background automation | Cloud API Direct | -| Need custom LLM config | `OpenHandsCloudWorkspace` | -| Want simplest setup | Cloud API Direct | - ## Next Steps - **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index efde8af7..a4533dc3 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -20,21 +20,16 @@ The PR review workflow supports two modes: | Mode | Description | Required Secrets | |------|-------------|-----------------| | **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | -| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN` | +| **Cloud Mode** | Runs the agent in an OpenHands Cloud sandbox | `LLM_API_KEY`, `GITHUB_TOKEN`, `OPENHANDS_CLOUD_API_KEY` | -### Cloud Mode Benefits - -- **No LLM setup** - Uses your OpenHands Cloud account's configured LLM -- **Faster CI completion** - Workflow exits immediately; review runs in background -- **Track progress** - Posts a comment on the PR with a link to the conversation URL +Both modes use the same Agent, LLM, and Conversation pattern - the only difference is the workspace type: +- **SDK mode**: Uses local workspace +- **Cloud mode**: Uses `OpenHandsCloudWorkspace` for a managed cloud sandbox -### Cloud Mode Prerequisites - - -The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments. +### Cloud Mode Benefits -Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud. - +- **Managed infrastructure** - Runs in OpenHands Cloud sandbox +- **Same agent logic** - Uses exactly the same Agent and Conversation as SDK mode ## Quick Start @@ -58,11 +53,11 @@ Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installatio cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml # 2. Configure secrets in GitHub Settings → Secrets - # Add: OPENHANDS_CLOUD_API_KEY (see https://docs.openhands.dev/openhands/usage/cloud/cloud-api#obtaining-an-api-key) + # Add: LLM_API_KEY, OPENHANDS_CLOUD_API_KEY # GITHUB_TOKEN is auto-available in GitHub Actions # 3. Update the workflow to use cloud mode: - # Set mode: cloud and remove llm-api-key + # Set mode: cloud # 4. (Optional) Create a "review-this" label in your repository ``` @@ -205,19 +200,19 @@ jobs: | Input | Description | Required | Default | |-------|-------------|----------|---------| | `mode` | Review mode: `sdk` or `cloud` | No | `sdk` | -| `llm-model` | LLM model (SDK mode only) | SDK mode | `anthropic/claude-sonnet-4-5-20250929` | -| `llm-base-url` | LLM base URL (SDK mode only) | No | `''` | +| `llm-model` | LLM model | No | `anthropic/claude-sonnet-4-5-20250929` | +| `llm-base-url` | LLM base URL | No | `''` | | `review-style` | Review style: `standard` or `roasted` | No | `roasted` | | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | -| `llm-api-key` | LLM API key (SDK mode only) | SDK mode | - | +| `llm-api-key` | LLM API key | Yes | - | | `github-token` | GitHub token for API access | Yes | - | | `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | Cloud mode | - | | `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` | ### Cloud Mode Workflow Example -For cloud mode, you don't need an LLM API key - just the cloud API key: +Cloud mode runs the same agent in an OpenHands Cloud sandbox: ```yaml icon="yaml" name: PR Review by OpenHands (Cloud Mode) @@ -249,13 +244,15 @@ jobs: uses: ./.github/actions/pr-review with: mode: cloud + llm-model: anthropic/claude-sonnet-4-5-20250929 review-style: roasted - openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + llm-api-key: ${{ secrets.LLM_API_KEY }} github-token: ${{ secrets.GITHUB_TOKEN }} + openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} ``` -In cloud mode, the workflow posts a comment on the PR with a link to the conversation URL, then exits immediately. The agent runs asynchronously in OpenHands Cloud and posts review comments when done. +Cloud mode uses `OpenHandsCloudWorkspace` to run the agent in a managed cloud sandbox. The LLM configuration is sent to the sandbox, so you need `LLM_API_KEY` for both modes. ## Related Files From 4b7b50c425ace1e65e3a9bc4d7a2644769161c68 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 10 Feb 2026 11:17:33 +0000 Subject: [PATCH 7/7] revert: Restore Cloud API Direct documentation Cloud mode uses /api/conversations endpoint which doesn't require LLM_API_KEY - it uses the user's cloud-configured LLM. Co-authored-by: openhands --- openhands/usage/use-cases/code-review.mdx | 34 +++--- sdk/guides/agent-server/cloud-workspace.mdx | 123 ++++++++++++++++++-- sdk/guides/github-workflows/pr-review.mdx | 37 +++--- 3 files changed, 157 insertions(+), 37 deletions(-) diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx index 33afa250..07ff7d51 100644 --- a/openhands/usage/use-cases/code-review.mdx +++ b/openhands/usage/use-cases/code-review.mdx @@ -21,17 +21,22 @@ The workflow supports two execution modes: | Mode | Description | Required Secrets | Best For | |------|-------------|-----------------|----------| -| **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | Local execution | -| **Cloud Mode** | Runs in an OpenHands Cloud sandbox | `LLM_API_KEY`, `GITHUB_TOKEN`, `OPENHANDS_CLOUD_API_KEY` | Managed infrastructure | - -Both modes use the same Agent, LLM, and Conversation pattern - the only difference is the workspace type: -- **SDK mode**: Uses local workspace -- **Cloud mode**: Uses `OpenHandsCloudWorkspace` for a managed cloud sandbox +| **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | Full control over LLM configuration | +| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN` | No LLM setup, faster CI | ### Cloud Mode Benefits -- **Managed infrastructure** - Runs in OpenHands Cloud sandbox -- **Same agent logic** - Uses exactly the same Agent and Conversation as SDK mode +- **No LLM setup** - Uses your OpenHands Cloud account's configured LLM +- **Faster CI completion** - Workflow exits immediately; review runs in background +- **Track progress** - Posts a comment on the PR with a link to the conversation URL + +### Cloud Mode Prerequisites + + +The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments. + +Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud. + ## How It Works @@ -150,18 +155,19 @@ Choose between two review styles: uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main with: mode: cloud - llm-model: anthropic/claude-sonnet-4-5-20250929 review-style: standard - llm-api-key: ${{ secrets.LLM_API_KEY }} - github-token: ${{ secrets.GITHUB_TOKEN }} openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` - + Go to your repository's **Settings → Secrets and variables → Actions** and add: - - **`LLM_API_KEY`**: Your LLM API key (get one from [OpenHands LLM Provider](/openhands/usage/llms/openhands-llms)) - **`OPENHANDS_CLOUD_API_KEY`**: See [Obtaining an API Key](/openhands/usage/cloud/cloud-api#obtaining-an-api-key) + + + Make sure you have an LLM configured in your [OpenHands Cloud account](https://app.all-hands.dev) and have connected your GitHub account. + @@ -176,6 +182,8 @@ Choose between two review styles: Open a PR and either: - Add the `review-this` label, OR - Request `openhands-agent` as a reviewer + + The workflow posts a comment with a link to track progress, then exits. The agent runs asynchronously in the cloud. diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index a3b9e050..8cf7ec90 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -5,9 +5,12 @@ description: Connect to OpenHands Cloud for fully managed sandbox environments. > A ready-to-run example is available [here](#ready-to-run-example)! -The [OpenHands Cloud](https://app.all-hands.dev) provides fully managed sandbox environments for agent execution. +The [OpenHands Cloud](https://app.all-hands.dev) provides fully managed sandbox environments for agent execution. There are two ways to use it: -The `OpenHandsCloudWorkspace` connects to OpenHands Cloud to provision sandboxes, allowing you to run agents with your own LLM configuration in a managed cloud environment. +1. **OpenHandsCloudWorkspace** - SDK integration for running agents with your own LLM configuration +2. **Cloud API Direct** - Launch one-off tasks that use your cloud-configured LLM and credentials + +This guide covers both approaches. ## Key Concepts @@ -203,19 +206,114 @@ cd agent-sdk uv run python examples/02_remote_agent_server/07_convo_with_cloud_workspace.py ``` -## Using in GitHub Actions +## Launching One-Off Tasks via Cloud API + +For scenarios where you want to launch a task and let it run asynchronously in the cloud (without waiting for completion), you can use the OpenHands Cloud API directly. This is particularly useful for: + +- **CI/CD workflows** - Trigger code reviews or automated tasks without blocking pipelines +- **Background processing** - Launch long-running tasks and check results later +- **Minimal configuration** - Only need an API key; LLM and GitHub credentials come from your cloud account + +### Key Benefits + +| Aspect | OpenHandsCloudWorkspace | Cloud API Direct | +|--------|------------------------|------------------| +| LLM Configuration | You provide `LLM_API_KEY` | Uses your cloud-configured LLM | +| GitHub Access | You provide `GITHUB_TOKEN` | Uses your cloud-configured credentials | +| Execution Model | Blocking (waits for completion) | Non-blocking (fire and forget) | +| Best For | Interactive scripts, testing | CI/CD, automated workflows | + +### How It Works + +The Cloud API creates a conversation that: +1. Uses your account's configured LLM (no API key needed in the request) +2. Has access to your GitHub credentials (if configured in your cloud account) +3. Runs asynchronously - you get a conversation URL to track progress +4. Can be viewed in the OpenHands Cloud UI + +### Example: PR Review Workflow + +This example from the [PR Review GitHub Action](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) demonstrates launching a code review task via the Cloud API: + +```python icon="python" +import json +import urllib.request + +def start_cloud_conversation( + cloud_api_url: str, + cloud_api_key: str, + initial_message: str, +) -> tuple[str, str]: + """Start a conversation via OpenHands Cloud API. + + This creates a conversation directly through the Cloud API, which: + - Uses the user's cloud-configured LLM (no LLM credentials needed) + - Uses the user's cloud-configured GitHub credentials + - Provisions a sandbox automatically + - Returns a conversation URL for tracking in the UI + + Args: + cloud_api_url: OpenHands Cloud API URL (e.g., https://app.all-hands.dev) + cloud_api_key: API key for OpenHands Cloud + initial_message: The initial prompt to send to the agent + + Returns: + Tuple of (conversation_id, conversation_url) + """ + url = f"{cloud_api_url}/api/conversations" + + payload = {"initial_user_msg": initial_message} + + data = json.dumps(payload).encode("utf-8") + request = urllib.request.Request(url, data=data, method="POST") + request.add_header("Authorization", f"Bearer {cloud_api_key}") + request.add_header("Content-Type", "application/json") -The `OpenHandsCloudWorkspace` can be used in GitHub Actions for CI/CD workflows. See the [PR Review Workflow](/sdk/guides/github-workflows/pr-review) for a complete example that demonstrates running code reviews in cloud mode: + with urllib.request.urlopen(request, timeout=120) as response: + result = json.loads(response.read().decode("utf-8")) + + conversation_id = result.get("conversation_id") + conversation_url = f"{cloud_api_url}/conversations/{conversation_id}" + return conversation_id, conversation_url + + +# Example usage for PR review +prompt = """ +Review the PR and identify issues that need to be addressed. + +## Pull Request Information +- **Repository**: OpenHands/software-agent-sdk +- **PR Number**: 1234 +- **Title**: Add new feature + +## Instructions +1. Fetch the PR diff using: gh pr diff 1234 --repo OpenHands/software-agent-sdk +2. Analyze the changes thoroughly +3. Post your review using the GitHub API (GITHUB_TOKEN is available) +""" + +conversation_id, conversation_url = start_cloud_conversation( + cloud_api_url="https://app.all-hands.dev", + cloud_api_key="your-api-key", + initial_message=prompt, +) + +print(f"Review started: {conversation_url}") +# The workflow can exit immediately - review continues in the cloud +``` + +### Using in GitHub Actions + +The PR Review workflow demonstrates a complete implementation: ```yaml icon="yaml" - name: Run PR Review (Cloud Mode) uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main with: mode: cloud - llm-model: anthropic/claude-sonnet-4-5-20250929 review-style: roasted - llm-api-key: ${{ secrets.LLM_API_KEY }} - github-token: ${{ secrets.GITHUB_TOKEN }} + # Only the cloud API key is needed - LLM and GitHub access + # come from your OpenHands Cloud account configuration openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} ``` @@ -223,6 +321,17 @@ The `OpenHandsCloudWorkspace` can be used in GitHub Actions for CI/CD workflows. See the full PR Review example: [examples/03_github_workflows/02_pr_review](https://github.com/OpenHands/software-agent-sdk/tree/main/examples/03_github_workflows/02_pr_review) +### When to Use Each Approach + +| Use Case | Recommended Approach | +|----------|---------------------| +| Interactive development | `OpenHandsCloudWorkspace` | +| Unit tests with cloud sandbox | `OpenHandsCloudWorkspace` | +| CI/CD code reviews | Cloud API Direct | +| Background automation | Cloud API Direct | +| Need custom LLM config | `OpenHandsCloudWorkspace` | +| Want simplest setup | Cloud API Direct | + ## Next Steps - **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx index a4533dc3..efde8af7 100644 --- a/sdk/guides/github-workflows/pr-review.mdx +++ b/sdk/guides/github-workflows/pr-review.mdx @@ -20,16 +20,21 @@ The PR review workflow supports two modes: | Mode | Description | Required Secrets | |------|-------------|-----------------| | **SDK Mode** (default) | Runs the agent locally in GitHub Actions | `LLM_API_KEY`, `GITHUB_TOKEN` | -| **Cloud Mode** | Runs the agent in an OpenHands Cloud sandbox | `LLM_API_KEY`, `GITHUB_TOKEN`, `OPENHANDS_CLOUD_API_KEY` | - -Both modes use the same Agent, LLM, and Conversation pattern - the only difference is the workspace type: -- **SDK mode**: Uses local workspace -- **Cloud mode**: Uses `OpenHandsCloudWorkspace` for a managed cloud sandbox +| **Cloud Mode** | Runs asynchronously in OpenHands Cloud | `OPENHANDS_CLOUD_API_KEY`, `GITHUB_TOKEN` | ### Cloud Mode Benefits -- **Managed infrastructure** - Runs in OpenHands Cloud sandbox -- **Same agent logic** - Uses exactly the same Agent and Conversation as SDK mode +- **No LLM setup** - Uses your OpenHands Cloud account's configured LLM +- **Faster CI completion** - Workflow exits immediately; review runs in background +- **Track progress** - Posts a comment on the PR with a link to the conversation URL + +### Cloud Mode Prerequisites + + +The OpenHands Cloud account that owns the `OPENHANDS_CLOUD_API_KEY` must have GitHub access to the repository you want to review. The agent running in cloud uses your account's GitHub credentials to fetch the PR diff and post review comments. + +Follow the [GitHub Installation Guide](/openhands/usage/cloud/github-installation) to connect your GitHub account to OpenHands Cloud. + ## Quick Start @@ -53,11 +58,11 @@ Both modes use the same Agent, LLM, and Conversation pattern - the only differen cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml # 2. Configure secrets in GitHub Settings → Secrets - # Add: LLM_API_KEY, OPENHANDS_CLOUD_API_KEY + # Add: OPENHANDS_CLOUD_API_KEY (see https://docs.openhands.dev/openhands/usage/cloud/cloud-api#obtaining-an-api-key) # GITHUB_TOKEN is auto-available in GitHub Actions # 3. Update the workflow to use cloud mode: - # Set mode: cloud + # Set mode: cloud and remove llm-api-key # 4. (Optional) Create a "review-this" label in your repository ``` @@ -200,19 +205,19 @@ jobs: | Input | Description | Required | Default | |-------|-------------|----------|---------| | `mode` | Review mode: `sdk` or `cloud` | No | `sdk` | -| `llm-model` | LLM model | No | `anthropic/claude-sonnet-4-5-20250929` | -| `llm-base-url` | LLM base URL | No | `''` | +| `llm-model` | LLM model (SDK mode only) | SDK mode | `anthropic/claude-sonnet-4-5-20250929` | +| `llm-base-url` | LLM base URL (SDK mode only) | No | `''` | | `review-style` | Review style: `standard` or `roasted` | No | `roasted` | | `sdk-version` | Git ref for SDK (tag, branch, or commit SHA) | No | `main` | | `sdk-repo` | SDK repository (owner/repo) | No | `OpenHands/software-agent-sdk` | -| `llm-api-key` | LLM API key | Yes | - | +| `llm-api-key` | LLM API key (SDK mode only) | SDK mode | - | | `github-token` | GitHub token for API access | Yes | - | | `openhands-cloud-api-key` | OpenHands Cloud API key (cloud mode only) | Cloud mode | - | | `openhands-cloud-api-url` | OpenHands Cloud API URL | No | `https://app.all-hands.dev` | ### Cloud Mode Workflow Example -Cloud mode runs the same agent in an OpenHands Cloud sandbox: +For cloud mode, you don't need an LLM API key - just the cloud API key: ```yaml icon="yaml" name: PR Review by OpenHands (Cloud Mode) @@ -244,15 +249,13 @@ jobs: uses: ./.github/actions/pr-review with: mode: cloud - llm-model: anthropic/claude-sonnet-4-5-20250929 review-style: roasted - llm-api-key: ${{ secrets.LLM_API_KEY }} - github-token: ${{ secrets.GITHUB_TOKEN }} openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }} + github-token: ${{ secrets.GITHUB_TOKEN }} ``` -Cloud mode uses `OpenHandsCloudWorkspace` to run the agent in a managed cloud sandbox. The LLM configuration is sent to the sandbox, so you need `LLM_API_KEY` for both modes. +In cloud mode, the workflow posts a comment on the PR with a link to the conversation URL, then exits immediately. The agent runs asynchronously in OpenHands Cloud and posts review comments when done. ## Related Files