### Build Project

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/README.md

Run this command to build the project and install dependencies before starting the server.

```bash
make build
```

--------------------------------

### Quick Start: Build an Agent with OpenHands SDK

Source: https://github.com/openhands/software-agent-sdk/blob/main/README.md

Demonstrates how to initialize an LLM, configure an agent with tools, and start a conversation to perform a task. Ensure the LLM_API_KEY environment variable is set.

```python
import os

from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool


llm = LLM(
    model="gpt-5.5",
    api_key=os.getenv("LLM_API_KEY"),
)

agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")
```

--------------------------------

### Install Skills from Marketplace

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills/README.md

Installs all skills defined in a specified marketplace configuration. Use the `force` parameter to reinstall existing skills.

```python
from openhands.sdk.skills import install_skills_from_marketplace

# Install all skills from a marketplace
installed = install_skills_from_marketplace("./my-marketplace", force=False)

for info in installed:
    print(f"Installed: {info.name}")
```

--------------------------------

### Check Apptainer Version

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md

Verify that Apptainer is installed by checking its version. This is a prerequisite for running Apptainer-related examples.

```bash
apptainer --version
```

--------------------------------

### Set LLM Credentials and Run Example

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/01_standalone_sdk/33_hooks/README.md

Configure environment variables for LLM API key, model, and base URL before running the main Python example script.

```bash
# Set your LLM credentials
export LLM_API_KEY="your-key"
export LLM_MODEL="gpt-5.5"  # optional
export LLM_BASE_URL="https://your-endpoint"  # optional

# Run example
python main.py
```

--------------------------------

### Create Installation Manager

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/extensions/installation/README.md

Instantiate the `InstallationManager` with the desired directory for storing installed extensions and an instance of your custom loader.

```python
manager = InstallationManager(
    installation_dir=Path("~/.myapp/widgets/installed").expanduser(),
    installation_interface=WidgetLoader(),
)
```

--------------------------------

### Run SDK Examples with All-Hands LLM Proxy

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/AGENTS.md

Use this command to run examples, setting the LLM base URL and API key. Ensure LLM_API_KEY is available or provided.

```bash
LLM_BASE_URL="https://llm-proxy.eval.all-hands.dev" LLM_API_KEY="$LLM_API_KEY" \
  uv run python examples/01_standalone_sdk/<example_name>.py
```

--------------------------------

### Install Apptainer on Linux

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md

Commands to install Apptainer on common Linux distributions.

```bash
sudo apt-get update
sudo apt-get install -y apptainer
```

```bash
sudo yum install -y apptainer
```

--------------------------------

### Install Skills from Marketplace

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills/README.md

Installs all skills defined in a marketplace configuration file. Supports an optional `force` parameter to re-install existing skills.

```APIDOC
## Install Skills from Marketplace

### Description
Installs all skills from a specified marketplace.

### Method Signature
```python
install_skills_from_marketplace(marketplace_path: str, force: bool = False)
```

### Parameters
- **marketplace_path** (str) - Required - The path to the marketplace configuration file.
- **force** (bool) - Optional - If True, re-installs existing skills. Defaults to False.

### Returns
- List of installed skill information objects.
```

--------------------------------

### Start OpenHands Agent Server

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/README.md

Start the server using Python's module execution. Default settings bind to 0.0.0.0:8000. Custom hosts and ports can be specified.

```bash
uv run python -m openhands.agent_server
```

```bash
uv run python -m openhands.agent_server --host localhost --port 3000
```

```bash
uv run python -m openhands.agent_server --reload
```

--------------------------------

### Initialize ApptainerWorkspace

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md

Examples for initializing the workspace using either a pre-built image or a local SIF file.

```python
from openhands.workspace import ApptainerWorkspace

# Use a pre-built agent server image
with ApptainerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8010,
) as workspace:
    result = workspace.execute_command("echo 'Hello from Apptainer!'")
    print(result.stdout)
```

```python
from openhands.workspace import ApptainerWorkspace

# Use an existing Apptainer SIF file
with ApptainerWorkspace(
    sif_file="/path/to/your/agent-server.sif",
    host_port=8010,
) as workspace:
    result = workspace.execute_command("ls -la")
    print(result.stdout)
```

--------------------------------

### Load Installed Skills

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills/README.md

Loads all skills that have been previously installed via the marketplace.

```APIDOC
## Load Installed Skills

### Description
Loads all skills that have been installed in the system.

### Method Signature
```python
load_installed_skills()
```

### Parameters
None

### Returns
- A list of skill objects, each containing name, description, and other relevant metadata.
```

--------------------------------

### List Installed Skills

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills/README.md

Retrieves metadata for all currently installed skills.

```APIDOC
## List Installed Skills

### Description
Lists the metadata for all installed skills.

### Method Signature
```python
list_installed_skills()
```

### Parameters
None

### Returns
- A list of objects, where each object contains information about an installed skill, such as its name and source.
```

--------------------------------

### List Installed Skills

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills/README.md

Retrieves metadata for all currently installed skills, including their names and original sources.

```python
from openhands.sdk.skills import list_installed_skills

# Get metadata for installed skills
installed = list_installed_skills()

for info in installed:
    print(f"{info.name}: {info.source}")
```

--------------------------------

### Workflow Input Example (Search Query)

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/03_github_workflows/04_datadog_debugging/README.md

Example configuration for the Datadog error debugging workflow when using a log query to search for errors.

```yaml
query_type: "log-query"
datadog_query: "service:deploy ClientDisconnect"
repo_list: "OpenHands/OpenHands,All-Hands-AI/infra,All-Hands-AI/deploy"
issue_repo: "All-Hands-AI/infra"
issue_parent: "https://github.com/All-Hands-AI/infra/issues/672"
```

--------------------------------

### JSON Configuration File Example

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/README.md

Example of a JSON configuration file for the OpenHands Agent Server. This file defines settings like API keys, CORS origins, conversation paths, and webhook configurations.

```json
{
  "session_api_key": "your-secret-api-key",
  "allow_cors_origins": ["https://your-frontend.com"],
  "allow_cors_origin_regex": null,
  "conversations_path": "workspace/conversations",
  "webhooks": [
    {
      "webhook_url": "https://your-webhook-endpoint.com/events",
      "method": "POST",
      "event_buffer_size": 10,
      "num_retries": 3,
      "retry_delay": 5,
      "headers": {
        "Authorization": "Bearer your-webhook-token"
      }
    }
  ]
}
```

--------------------------------

### Ruff linting output example

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/02_loading_plugins/example_plugins/code-quality/skills/linting/SKILL.md

Sample output showing identified linting errors and fixable status.

```text
example.py:1:1: F401 [*] `os` imported but unused
example.py:5:5: E302 Expected 2 blank lines, found 1
Found 2 errors (1 fixable).
```

--------------------------------

### Run All Integration Tests Locally

Source: https://github.com/openhands/software-agent-sdk/blob/main/tests/integration/README.md

Executes all integration tests using the specified LLM configuration. Ensure you have the necessary environment setup.

```bash
uv run python tests/integration/run_infer.py --llm-config '{"model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929"}'
```

--------------------------------

### Copy Workflow File to GitHub Actions Directory

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/03_github_workflows/02_pr_review/README.md

Use this command to copy the example workflow file to the correct location in your repository for GitHub Actions to recognize it.

```bash
cp examples/03_github_workflows/02_pr_review/workflow.yml .github/workflows/pr-review-by-openhands.yml
```

--------------------------------

### GET /conversations/{conversation_id}

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/README.md

Get conversation details.

```APIDOC
## GET /conversations/{conversation_id}

### Description
Get conversation details.

### Method
GET

### Endpoint
/conversations/{conversation_id}

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The ID of the conversation
```

--------------------------------

### GET /conversations/{conversation_id}/events

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/README.md

Get events for a conversation.

```APIDOC
## GET /conversations/{conversation_id}/events

### Description
Get events for a conversation.

### Method
GET

### Endpoint
/conversations/{conversation_id}/events

### Parameters
#### Path Parameters
- **conversation_id** (string) - Required - The ID of the conversation
```

--------------------------------

### ApptainerWorkspace Usage Examples

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md

Demonstrates various ways to initialize and use the ApptainerWorkspace, including using pre-built images, SIF files, mounting directories, and enabling GPU support.

```APIDOC
## ApptainerWorkspace Initialization

### Description
This section covers the initialization of the `ApptainerWorkspace` class with different configurations.

### Method
Context Manager (`with` statement)

### Endpoint
N/A (Class-based)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from openhands.workspace import ApptainerWorkspace

# Option 1: Use Pre-built Agent Server Image (Recommended)
with ApptainerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8010,
) as workspace:
    result = workspace.execute_command("echo 'Hello from Apptainer!'")
    print(result.stdout)

# Option 2: Use Existing SIF File
with ApptainerWorkspace(
    sif_file="/path/to/your/agent-server.sif",
    host_port=8010,
) as workspace:
    result = workspace.execute_command("ls -la")
    print(result.stdout)

# Option 3: Mount Host Directory
with ApptainerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8010,
    mount_dir="/path/to/host/directory",
) as workspace:
    result = workspace.execute_command("ls /workspace")
    print(result.stdout)

# Option 4: Enable NVIDIA GPU Passthrough
with ApptainerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8010,
    enable_gpu=True,
) as workspace:
    result = workspace.execute_command("nvidia-smi -L")
    print(result.stdout)
```

### Response
#### Success Response (200)
N/A (Context manager handles setup and teardown)

#### Response Example
N/A
```

--------------------------------

### Load Installed Skills

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/05_skills_and_plugins/04_mixed_marketplace_skills/README.md

Loads all skills that have been previously installed into the system. This allows access to their functionalities.

```python
from openhands.sdk.skills import load_installed_skills

# Load all installed skills
skills = load_installed_skills()

for skill in skills:
    print(f"Skill: {skill.name}")
    print(f"Description: {skill.description}")
```

--------------------------------

### Clone and Build Agent SDK

Source: https://github.com/openhands/software-agent-sdk/blob/main/DEVELOPMENT.md

Clone the repository and build the SDK using make.

```bash
git clone https://github.com/OpenHands/agent-sdk.git
cd agent-sdk
make build
```

--------------------------------

### Run Apptainer Sandboxed Server Example

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-workspace/openhands/workspace/apptainer/README.md

Execute a Python script that sets up an Apptainer workspace, runs agent conversations, performs file operations in a sandboxed environment, and handles cleanup. Ensure you are in the correct directory before running.

```python
cd examples/02_remote_agent_server
python 07_convo_with_apptainer_sandboxed_server.py
```

--------------------------------

### Datadog Query Examples

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/03_github_workflows/04_datadog_debugging/README.md

Examples of Datadog queries to identify different types of errors. Use these to specify the errors you want the agent to investigate.

```yaml
# ClientDisconnect errors
service:deploy ClientDisconnect
```

```yaml
# Server errors (5xx)
service:deploy http.status_code:5*
```

```yaml
# Database errors
service:deploy (database OR postgresql) status:error
```

```yaml
# Authentication errors
service:deploy (authentication OR authorization) status:error
```

```yaml
# Rate limit errors
service:deploy rate_limit status:error
```

--------------------------------

### Local Testing Setup

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/03_github_workflows/01_basic_action/README.md

Before deploying to GitHub Actions, test the agent script locally by setting environment variables for API key and model, creating a prompt file, and running the script.

```bash
export LLM_API_KEY="your-api-key"
export LLM_MODEL="gpt-5.5"

# Create a test prompt
echo "Check for outdated dependencies in requirements.txt and create a PR to update them" > prompt.txt

# Run the agent
python examples/03_github_workflows/01_routine_maintenance/agent_script.py prompt.txt
```

--------------------------------

### Manage Extensions with InstallationManager

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/extensions/installation/README.md

Utilize the `InstallationManager` to install extensions from various sources, list, load, enable, disable, update, and uninstall them. Ensure extension names follow kebab-case.

```python
# Install from a local path or remote source
info = manager.install("github:owner/my-widget", ref="v1.0.0")
info = manager.install("/path/to/local/widget")

# Force-overwrite an existing installation (preserves enabled state)
info = manager.install("github:owner/my-widget", force=True)

# List / load
all_info = manager.list_installed()        # List[InstallationInfo]
widgets  = manager.load_installed()        # List[Widget]  (enabled only)

# Enable / disable
manager.disable("my-widget")               # excluded from load_installed()
manager.enable("my-widget")                # included again

# Look up a single extension
info = manager.get("my-widget")            # InstallationInfo | None

# Update to latest from the original source
info = manager.update("my-widget")

# Remove completely
manager.uninstall("my-widget")
```

--------------------------------

### Workflow Input Example (Specific Error ID)

Source: https://github.com/openhands/software-agent-sdk/blob/main/examples/03_github_workflows/04_datadog_debugging/README.md

Example configuration for the Datadog error debugging workflow when debugging a specific error using its ID.

```yaml
query_type: "log-error-id"
datadog_query: "2adba034-ab5a-11f0-b04e-da7ad0900000"
repo_list: "OpenHands/OpenHands,All-Hands-AI/infra,All-Hands-AI/deploy"
issue_repo: "All-Hands-AI/infra"
issue_parent: "https://github.com/All-Hands-AI/infra/issues/672"
```

--------------------------------

### Development and Testing Commands

Source: https://github.com/openhands/software-agent-sdk/blob/main/openhands-tools/openhands/tools/AGENTS.md

Commands for setting up the development environment, running pre-commit hooks, and executing the tool test suite.

```bash
make build
```

```bash
uv run pre-commit run --files <path>
```

```bash
uv run pytest tests/tools -k <pattern>
```