diff --git a/openhands/usage/use-cases/code-review.mdx b/openhands/usage/use-cases/code-review.mdx
index 65a25504..07ff7d51 100644
--- a/openhands/usage/use-cases/code-review.mdx
+++ b/openhands/usage/use-cases/code-review.mdx
@@ -13,6 +13,30 @@ 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`, `GITHUB_TOKEN` | No LLM setup, faster CI |
+
+### 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
+
+
+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
@@ -44,60 +68,126 @@ 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 }}
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+ ```
+
+
+
+ Go to your repository's **Settings → Secrets and variables → Actions** and add:
+ - **`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.
+
+
+
+
+ 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 posts a comment with a link to track progress, then exits. The agent runs asynchronously in the cloud.
+
+
+
+
## Composite Action
@@ -112,18 +202,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 | - |
+| `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` |
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 posts a comment with a link to track progress, then exits immediately. The agent runs asynchronously in OpenHands Cloud using your configured LLM.
+
+
## Customization
### Repository-Specific Review Guidelines
@@ -262,6 +359,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/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx
index cf4164d2..8cf7ec90 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
@@ -28,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.
@@ -206,9 +206,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
diff --git a/sdk/guides/github-workflows/pr-review.mdx b/sdk/guides/github-workflows/pr-review.mdx
index 9dfb5820..efde8af7 100644
--- a/sdk/guides/github-workflows/pr-review.mdx
+++ b/sdk/guides/github-workflows/pr-review.mdx
@@ -13,19 +13,61 @@ 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.
-## Quick Start
+## Review Modes
-```bash
-# 1. Copy workflow to your repository
-cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review.yml
+The PR review workflow supports two modes:
-# 2. Configure secrets in GitHub Settings → Secrets
-# Add: LLM_API_KEY
+| 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` |
-# 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
-```
+### 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
+
+
+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
+
+
+
+ ```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
+
+ # 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 (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
+
+ # 4. (Optional) Create a "review-this" label in your repository
+ ```
+
+
## Features
@@ -33,6 +75,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 +204,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 | - |
+| `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
+
+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)
+
+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
+ openhands-cloud-api-key: ${{ secrets.OPENHANDS_CLOUD_API_KEY }}
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+
+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