Skip to content

Latest commit

 

History

History
156 lines (126 loc) · 7.19 KB

README.md

File metadata and controls

156 lines (126 loc) · 7.19 KB

OpenHands Adapter for NVIDIA NeMo Fabric

This package runs one persistent OpenHands SDK conversation for each NeMo Fabric runtime. It maps normalized model configuration, system instructions, built-in tool selection, MCP servers, skills, the workspace, and the per-invocation iteration limit into OpenHands.

Install

Install the tested OpenHands SDK and tools, then install the adapter:

pip install "openhands-sdk==1.50.0" "openhands-tools==1.50.0" \
  "litellm==1.100.1" "mcp==1.28.1"
pip install nemo-fabric-adapters-openhands

The OpenHands SDK and tools 1.50.0 pair is validated with NVIDIA NIM. OpenHands SDK 1.50.0 requires FastMCP 3.x, whose client requires MCP 1.x. Pin LiteLLM and MCP together in OpenShell task images: newer LiteLLM releases can require MCP 2.x, which is incompatible with this FastMCP client.

The adapter package supports Python 3.11 or later, while OpenHands requires Python 3.12 or later. The adapter package does not install OpenHands.

For a source checkout, install the adapter and the compatible OpenHands packages in the repository environment, then select that interpreter for Python adapter processes:

uv sync --group adapter-tests
uv pip install "openhands-sdk==1.50.0" "openhands-tools==1.50.0" \
  "litellm==1.100.1" "mcp==1.28.1"
export ADAPTER_PYTHON="$PWD/.venv/bin/python"

Configure

Select nvidia.fabric.openhands. The built-in tool names are terminal (alias bash) and file_editor (alias edit). OpenHands always retains its internal finish and reasoning tools.

from nemo_fabric import EnvironmentConfig
from nemo_fabric import FabricConfig
from nemo_fabric import HarnessConfig
from nemo_fabric import InstructionConfig
from nemo_fabric import InstructionsConfig
from nemo_fabric import ModelConfig
from nemo_fabric import RuntimeConfig
from nemo_fabric import ToolsConfig

config = FabricConfig(
    harness=HarnessConfig(adapter_id="nvidia.fabric.openhands"),
    models={
        "default": ModelConfig(
            provider="nvidia",
            model="nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
            api_key_env="NVIDIA_API_KEY",
            base_url="https://integrate.api.nvidia.com/v1",
        )
    },
    instructions=InstructionsConfig(
        system=InstructionConfig(content="Review the requested code change.")
    ),
    tools=ToolsConfig(enabled=["file_editor"]),
    runtime=RuntimeConfig(max_turns=20),
    environment=EnvironmentConfig(provider="local", workspace="."),
)

Relative skill and workspace paths resolve from the configuration base directory. Each skill path must be a directory containing SKILL.md. The adapter disables ambient OpenHands user, public, project, and memory loading; only explicitly configured NeMo Fabric skills are loaded.

For provider="nvidia", the adapter adds LiteLLM's nvidia_nim/ dispatch prefix while preserving the served model ID, including its nvidia/ namespace. This also supports self-hosted NIM endpoints through base_url. An existing nvidia_nim/ prefix is retained once.

The adapter configures the OpenHands SDK standard summarizing condenser, default_condenser, with the agent model. When the history sent to the model exceeds 80 events, or exceeds the model input token limit when OpenHands knows it, OpenHands replaces older events with a model-generated summary and keeps the first 4 events. When the model rejects a request for exceeding its context window, OpenHands condenses the history and continues instead of failing the invocation. Summarization calls count toward invocation usage, and each condensation step counts toward runtime.max_turns. NeMo Fabric does not expose condenser tuning parameters.

To keep the full conversation history and make no summarization calls, set the condenser harness setting to none. The default value, default, enables the condenser, and any other value is rejected. The following example turns the condenser off:

from nemo_fabric import HarnessConfig

harness = HarnessConfig(
    adapter_id="nvidia.fabric.openhands",
    settings={"condenser": "none"},
)

The initial adapter does not support Relay telemetry, native streaming, interactive confirmation, MCP authentication, or per-server MCP tool filters.

Understand the Runtime Lifecycle

The adapter runs the OpenHands SDK directly in a persistent Python adapter process. It does not start or connect to an OpenHands server. start creates one local conversation for the NeMo Fabric runtime, and ordered invocations reuse that conversation and its history.

flowchart TD
  Fabric["NeMo Fabric runtime"] -->|"NDJSON over stdio"| Adapter
  subgraph Python["One persistent Python adapter process"]
    Adapter["OpenHands adapter"] --> SDK["OpenHands SDK"]
    SDK --> Conversation["One local conversation"]
  end
  Conversation --> Provider["Model-provider endpoint"]
  Conversation --> MCP["Configured MCP servers"]
  Conversation --> Workspace["NeMo Fabric workspace"]
Loading

Each invocation returns only the final response and usage for that turn. stop closes the conversation and removes the adapter-owned temporary profile state. Create a new runtime to change the model, workspace, tools, MCP servers, or skills.

Usage requires invocation-local SDK token records. If a request fails before the SDK records usage, or a response contains no usage, the adapter leaves token counters unknown instead of reporting the SDK's zero-initialized accumulator. Recorded tokens remain available after a later invocation failure. Cost is unknown unless the SDK records a cost for every returned response; an unmapped model's default accumulated cost does not establish a free request. Reported input tokens include cached input, following LiteLLM's normalized prompt_tokens convention. The adapter sets input_tokens_include_cache to true and does not add the cache count again or infer a missing cache breakdown.

Runtime Health

The adapter advertises live and active checks qualified against OpenHands SDK 1.50.0. live reads the owned LocalConversation native closure flags. active also requires the native lazy-initialization flag to confirm that the conversation's request interface has initialized. Before the first invocation initializes the conversation, active returns unknown/capabilities_unverified. Checks do not initialize the conversation.

A running native arun() task reports busy and remains healthy. Native closure returns failed/session_closed; missing native lifecycle fields return unknown/capabilities_unverified. Checks use no conversation lock and do not submit messages, call a model, initialize tools or MCP, or alter conversation state. The shared host applies the caller's remaining deadline and invalidates observations when ownership changes. Health timeouts do not cancel an invocation.

ready remains unsupported because no qualified native read-only readiness response exists. Passing active does not establish model access, credential validity, or tool connectivity.

Refer to the SDK health-check overview for shared behavior and a comparison of native evidence across adapters.