/nemo-fabric-integrate

name: nemo-fabric-integrate
description: Use this skill when integrating NVIDIA NeMo Fabric into a consumer application, service, evaluation harness, or platform through the typed Python SDK — translating the consumer's own application, job, or deployment config into an in-memory FabricConfig, choosing the single-invocation convenience API or an explicitly started runtime, validating with plan and doctor, and consuming normalized results, artifacts, and telemetry.
license: Apache-2.0
metadata:
  author: NVIDIA Corporation and Affiliates

Integrate NVIDIA NeMo Fabric Through The Python SDK

Use this skill when a consumer codebase — an application, service, evaluation harness, or platform — needs to run agent harnesses through NeMo Fabric's typed Python SDK. The consumer owns its own configuration object and translates it into an in-memory `FabricConfig`; NeMo Fabric owns adapter selection, the runtime lifecycle, and normalized results.

Integration Boundary

Use the public, in-memory contract. These rules keep a consumer integration supported and upgrade-safe:

• Import only from the public `nemo_fabric` package. Never import `_native` or

any adapter-internal module.

• Build configuration as a typed `FabricConfig` in memory and pass it directly to

NeMo Fabric. Create every deployment or evaluation variant with ordinary Python functions and `model_copy(deep=True)`. A platform integration can serialize the typed config inside a private transient run specification when it crosses a process boundary; that transport is not a public authoring format.

• Let NeMo Fabric own harness control. Do not reimplement start, invoke, or stop

logic, and do not manage adapter threads, sessions, or processes directly.

• Treat `runtime_id`, `invocation_id`, and `request_id` as opaque correlation

strings, not parsable or reusable state.

Refer to [config-mapping.md](references/config-mapping.md) for how to translate a consumer config object into `FabricConfig`, and for the full list of mechanics that stay hidden behind this boundary.

Install And Set Up The Environment

The consumer or its execution environment owns installation; NeMo Fabric validates runtime assumptions but never installs harnesses or credentials at run time.

• NeMo Fabric supports Python 3.11 through 3.14. Use Python 3.11 through 3.13

for Hermes Agent; the Harbor integration requires Python 3.12 or later.

• Install the runtime with `uv pip install nemo-fabric` (add the `harbor` extra

for the Harbor integration). Refer to the [installation guide](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/getting-started/install.mdx).

• Select the harness adapter through `HarnessConfig.adapter_id`. To install the

NeMo Fabric runtime, adapter, and supported harness in one environment, use `nemo-fabric[claude]`, `nemo-fabric[codex]`, or `nemo-fabric[deepagents]`.

• Hermes Agent 0.20 and later is no longer installable from PyPI. Follow the

[Hermes Agent installation guide](https://hermes-agent.nousresearch.com/docs/installation), then install the `nemo-fabric[hermes-agent]` package into the Python environment that runs Hermes Agent. These packages do not install Hermes Agent.

• In a separate adapter environment, install

`nemo-fabric-adapters-<adapter>[harness]`. This installs the adapter and supported harness dependencies without the NeMo Fabric runtime. Use `full` instead when that adapter package provides package-installable optional integrations.

• Point the runtime to a separate adapter environment with `ADAPTER_PYTHON`.

Use matching NeMo Fabric release versions for the runtime and adapter package unless a different pairing has been explicitly validated.

• If the adapter environment already manages a compatible harness, install the

bare `nemo-fabric-adapters-<adapter>` distribution. Bare adapter distributions contain only adapter-owned runtime dependencies.

• LangChain Deep Agents and Hermes Agent adapter packages provide `relay` and

include the NeMo Relay Python package in `full`. The Hermes Agent extras do not install Hermes Agent. Claude and Codex do not provide `relay`; their `harness` and `full` extras install the supported `nemo-relay` CLI alongside the harness SDK.

• Provide model credentials through environment variables named by the config

(`ModelConfig.api_key_env`), never as literals in code.

• Confirm the native extension is importable; SDK calls raise

`FabricNativeUnavailableError` when it is missing.

Build The Typed Config From Consumer Config

Map the consumer's application, job, or deployment object into a `FabricConfig` with the public models and helper methods:

from nemo_fabric import (
    FabricConfig,
    HarnessConfig,
    InstructionConfig,
    InstructionsConfig,
    MetadataConfig,
    ModelConfig,
    RuntimeConfig,
    ToolsConfig,
)


def to_tools_config(job) -> ToolsConfig | None:
    enabled = job.enabled_tools
    blocked = list(job.blocked_tools)
    if enabled is None and not blocked:
        return None
    return ToolsConfig(
        enabled=None if enabled is None else list(enabled),
        blocked=blocked,
    )


def to_fabric_config(job) -> FabricConfig:
    config = FabricConfig(
        metadata=MetadataConfig(name=job.name),
        harness=HarnessConfig(adapter_id=job.adapter_id, resolution="preinstalled"),
        models={
            "default": ModelConfig(
                provider=job.provider,
                model=job.model,
                api_key_env=job.api_key_env,
                base_url=job.base_url,
            )
        },
        instructions=(
            InstructionsConfig(
                system=InstructionConfig(
                    content=job.system_instruction,
                    mode=job.system_instruction_mode,
                ),
            )
            if job.system_instruction is not None
            else None
        ),
        runtime=RuntimeConfig(
            input_schema="chat",