Nemo Fabric Integrate

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 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.

• Choose supported Python interpreters for the runtime, Harbor, and adapter environments from the installation guide.
• Install the runtime with uv pip install nemo-fabric (add the harbor extra for the Harbor integration).
• 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].
• Install Hermes Agent separately from the Fabric adapter. Follow the Hermes integration guide for the current compatible interpreter, source checkout, Relay dependencies, and adapter installation. The nemo-fabric[hermes-agent] extra does 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 adapter packages provide relay and include the NeMo Relay Python package in full. 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.
• For descriptor inspection without harness SDKs, install the separate nemo-fabric-adapter-catalog package and call nemo_fabric_adapter_catalog.get_adapter_descriptor(adapter_id) or get_target_descriptor(target_id). Refer to the catalog guide. Catalog resources do not register execution runners; unknown IDs raise KeyError. Validate against the task environment's descriptor before relying on a snapshot claim. Catalog source versions and fingerprints are not runtime-observed provenance.

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",
            output_schema="message",
            timeout_seconds=job.timeout_seconds,
            max_turns=job.max_turns,
        ),
        tools=to_tools_config(job),
    )
    config.add_skill_path(job.skill_dir)
    config.add_mcp_server(
        "github",
        transport="streamable-http",
        url="${GITHUB_MCP_URL}",
        exposure="harness_native",
    )
    return config

• Shape capabilities with ToolsConfig, add_tool_definition, block_tools, add_skill_path, remove_skill_path, add_mcp_server, remove_mcp_server, and enable_relay.
• Use add_tool_definition only when the selected adapter accepts tools.definitions and publishes a tool_definition_schema.
• Use a restricted allowed_tools list or non-empty blocked_tools on add_mcp_server only when the selected adapter declares both mcp and mcp.tool_filters. An unfiltered server requires only mcp. allowed_tools=None exposes every discovered tool, while an empty list exposes none; blocked tools are removed after applying that allowlist. Tool names must be non-blank, and planning rejects a tool that appears in both lists.
• Configure MCP authentication only when the selected adapter declares mcp.auth.oauth2 or mcp.auth.service_account, matching the authentication type.
• Create deployment or evaluation variants with model_copy(deep=True) and ordinary Python functions; each copy plans and runs independently.
• Pass base_dir=... to any Fabric call when the config uses relative paths, so skills, workspaces, and artifacts anchor to the consumer's own layout.

The repository code_review_agent example shows this pattern end to end with complete Hermes Agent, Codex, Deep Agents, environment, MCP, and telemetry variants. Reuse it rather than duplicating config construction.

Choose A Lifecycle

For Deep Agents, mini-SWE-agent, and the LangGraph custom-agent example, pass the same UUID string through RunRequest.relay_session_root on each conversation turn to group Relay trajectories under one session. Core forwards the typed field as AgentRunRequest.relay_session_root; context keys do not control Relay propagation. An unusable UUID preserves per-request behavior. The remaining adapters do not consume this field.

Pick the smallest lifecycle the consumer needs:

• Single invocation — one input, no retained state after the call. await Fabric().run(config, input=...) runs the full start, invoke, and stop cycle and returns a RunResult. Pass request=RunRequest(...) instead of input=... when the invocation needs a caller-owned request ID or context (the two are mutually exclusive).
• Stateful runtime — ordered turns over one logical harness lifecycle. Start it with start_runtime(...) and use the returned Runtime as an async context manager so cleanup runs on exit — shutdown is attempted, not guaranteed (stop() can raise FabricRuntimeError; see Consume Results And Handle Errors). A runtime accepts one active invocation at a time; overlapping calls raise FabricStateError.
• Native OpenAI stream — adapter-native OpenAI Chat Completions chunks plus a separate terminal normalized result. Check runtime.supports_openai_streaming, call runtime.invoke_openai_stream(...), iterate the returned OpenAIInvokeStream, and then await stream.result(). The selected adapter descriptor must declare capabilities.streaming. Each yielded mapping has object == "chat.completion.chunk"; an empty stream is valid. If iteration stops early, call await stream.aclose() to drain without cancelling the target invocation. This path does not require NeMo Relay or streaming=True.
• NVIDIA NeMo Relay stream — live, raw ATOF records plus a terminal normalized result. Install nemo-fabric[streaming] to include the matching collector for the default embedded streaming path. Enable NeMo Relay, pass streaming=True to start_runtime(...), call runtime.invoke_stream(...), iterate the returned InvokeStream, and then await stream.result(). Iteration ending does not indicate invocation success; invocation exceptions raise from result(), while harness-reported failures remain normalized RunResult values. If iteration stops early, call await stream.aclose() before starting another turn. aclose() waits for the turn to finish; it does not cancel the harness invocation. The SDK intentionally exposes only ATOF records generated by NeMo Relay. This path is independent of native OpenAI streaming. The collector registers the request before the agent is invoked, then routes the matching ATOF root scope and its descendants by request ID and UUID ancestry. By default, streaming starts an embedded collector. Set launch_collector=False to use an externally managed collector; configure its base URL as the nemo-fabric-stream sink with transport="ndjson". The runtime directs Relay to <base-url>/v1/atof and uses the collector control and stream endpoints. The bundled Pi adapter requires the embedded collector. Do not set launch_collector=False for Pi streaming. The embedded collector waits up to completion_wait_timeout seconds (1.0 by default) for a late agent_settled marker. The collector limits each record to 1 MiB and each request queue to 1,024 records or 16 MiB of encoded data. The streaming=True flag does not enable NeMo Relay by itself. Without streaming=True, startup leaves the NeMo Relay configuration unchanged.

The selected adapter owns the execution topology. The bundled Claude, Codex, Deep Agents, and Hermes Agent adapters retain their native client, graph/checkpointer, or agent/database inside one local host for the full runtime. Local process and python adapters use this host lifecycle; consumers do not select another local execution mechanism in FabricConfig. Do not replay an invocation after a runtime failure. Stop the failed runtime and explicitly start a new one according to the application's retry policy.

The lifecycle fragment below shows the available forms. It assumes the caller has already set config = to_fabric_config(job) and chosen base, as described in the configuration example above:

import asyncio

from nemo_fabric import Fabric


async def main() -> None:
    fabric = Fabric()

    # Single invocation
    result = await fabric.run(config, base_dir=base, input="Review the changes.")

    # Multi-turn
    async with await fabric.start_runtime(config, base_dir=base) as runtime:
        first = await runtime.invoke(input="Inspect the repository")
        second = await runtime.invoke(input="Now review the latest patch")

    # Adapter-native OpenAI Chat Completions chunks
    async with await fabric.start_runtime(config, base_dir=base) as runtime:
        if runtime.supports_openai_streaming:
            stream = runtime.invoke_openai_stream(input="Review the latest patch")
            async for chunk in stream:
                print(chunk)
            openai_streamed_result = await stream.result()

    # NeMo Relay streaming
    streaming_config = config.model_copy(deep=True).enable_relay()
    async with await fabric.start_runtime(
        streaming_config,
        base_dir=base,
        streaming=True,
    ) as runtime:
        stream = runtime.invoke_stream(input="Review the latest patch")
        async for record in stream:
            print(record)
        streamed_result = await stream.result()


asyncio.run(main())

NeMo Fabric owns no application scheduling queue, worker pool, retry policy, or global concurrency policy. Each runtime still permits only one active invocation; start independent runtimes for parallel work. The NeMo Relay streaming path uses an internal bounded transport queue and TCP backpressure only to carry one invocation's ATOF records. Treat stream.result() as authoritative, and reconstruct nested work from ATOF uuid and parent_uuid fields rather than stream order.

For native OpenAI streaming, the SDK owns the authenticated loopback HTTP transport, chunked NDJSON framing, and correlation values. Consumer code supplies no listener or credentials. The adapter executes exactly one invocation, and the terminal RunResult remains separate from the chunk stream. Fully consume the stream or call await stream.aclose() before starting another turn. Awaiting stream.result() also drains and discards unread native OpenAI chunks, so consume the iterator first when the application needs every chunk.