Skip to content
Closed
Show file tree
Hide file tree
Changes from 8 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 78 additions & 120 deletions docs/about-nemo-fabric/overview.mdx
Original file line number Diff line number Diff line change
@@ -1,130 +1,88 @@
---
title: "NVIDIA NeMo Fabric"
title: "NVIDIA NeMo Fabric Documentation"
sidebar-title: "Overview"
slug: "/about-nemo-fabric/overview"
description: "Configure, plan, run, and observe agent harnesses through one typed execution contract."
template-library-version: "1.0.0"
---
{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0 */}

NeMo Fabric is the harness-management layer that turns multiple agent runtimes
into one configurable, observable execution surface. Applications use the same
versioned config, lifecycle, result, artifact, and telemetry contracts whether
the selected harness is Hermes, Codex SDK, or a custom adapter.
[NVIDIA NeMo Fabric](https://github.com/NVIDIA/NeMo-Fabric) is the
harness-management layer that turns multiple agent runtimes into one
configurable, observable execution surface. Applications use the same versioned
config, lifecycle, result, artifact, and telemetry contracts whether the
selected harness is [Hermes Agent](https://hermes-agent.nousresearch.com/docs/),
[Codex SDK](https://openai.com/codex/), or a custom adapter.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

NeMo Fabric owns the seam between an application and its harness. It resolves
configuration, selects an adapter, drives the runtime lifecycle,
and returns normalized evidence without leaking harness-specific control code
into the caller.
configuration, selects an adapter, drives the runtime lifecycle, and returns
normalized evidence without leaking harness-specific control code into the
caller.

## What NeMo Fabric gives you
## Benefits

NeMo Fabric gives applications one contract across every supported harness.

<CardGroup cols={2}>
<Card title="Portable configuration">
<Card title="Portable Configuration">
Use a versioned `agent.yaml` package or construct the same typed
`FabricConfig` in Python. Applications create variants from typed copies;
portable file packages can use ordered profiles.
</Card>
<Card title="Harness-neutral execution">
<Card title="Harness-Neutral Execution">
Plan and invoke different harnesses through one Rust core, CLI, and Python
SDK instead of embedding harness launch logic in every consumer.
</Card>
<Card title="Typed lifecycle contracts">
<Card title="Typed Lifecycle Contracts">
Resolve configs, inspect capabilities, run one-shot jobs, and hold
multi-turn runtimes with typed requests, plans, handles, and results.
</Card>
<Card title="Normalized evidence">
<Card title="Normalized Evidence">
Collect output, errors, lifecycle events, artifact manifests, and telemetry
references in stable contracts suitable for platforms and evaluations.
</Card>
</CardGroup>

## How NeMo Fabric fits

```text
Application or evaluation harness
|
| Python SDK or `fabric` CLI
v
NeMo Fabric Rust core
config -> plan -> lifecycle
|
| resolved adapter contract
v
Hermes | Codex SDK | custom harness
|
v
RunResult + artifacts + events + telemetry references
```

The CLI and Python SDK are separate interfaces over the same core. File-backed
and typed configs converge on the same resolved config and run-plan contracts.
Adapters own harness-specific preparation and invocation; consumers own the
request and the use of returned evidence.

## Quick start

Install `just` 1.50.0+ if it is not already available.

```bash
cargo install just --locked
```

Refer to the [official installation guide](https://just.systems/man/en/installation.html)
for more details.

Ensure that the Cargo bin directory is in your `PATH`:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

Create a Python virtual environment and activate it (replace `3.13` with your preferred Python version):

```bash
uv venv -p 3.13 --seed .venv
source .venv/bin/activate
```

Install the Python SDK with its native binding and the CLI from a source
checkout:
## Use Cases

```bash
just build-all
```
Teams use NeMo Fabric to run agents through a single contract, hold multi-turn
sessions over a live harness, and integrate agent execution into platforms and
evaluation pipelines.

Run the example through the Python SDK:
| Use Case | Reader Goal | Result |
| --- | --- | --- |
| Application integration | Run one-shot agent jobs from an application that owns its own config. | A normalized `RunResult` with output, artifacts, events, and telemetry references. |
| Multi-turn runtimes | Drive several ordered turns over one live harness runtime. | A stateful runtime handle you start, invoke, and stop through one lifecycle contract. |
| Platform and evaluation harnesses | Plan and invoke many harnesses behind one typed surface. | Stable, harness-neutral evidence suitable for platforms and evaluations. |

```python
import asyncio
from examples.code_review_agent import BASE_DIR, hermes_config
from nemo_fabric import Fabric
### Application Integration

An application owns its job config and consumes returned evidence. Configure an
agent package or typed `FabricConfig`, run it through the Python SDK, and read
the normalized `RunResult`. Refer to the
[Python SDK guide](/nemo/fabric/sdk/python-sdk) for typed requests and one-shot
run examples.

async def main() -> None:
config = hermes_config()
client = Fabric()
result = await client.run(
config,
base_dir=BASE_DIR,
input="Reply with exactly: fabric works",
)
### Multi-Turn Runtimes

print(result.status)
When a workflow needs several ordered turns over one live harness, start a
runtime and invoke it turn by turn before stopping it. Refer to the
[Runtime reference](/reference/api/python-library-reference/runtime) for the
start, invoke, and stop lifecycle.

### Platform and Evaluation Harnesses

asyncio.run(main())
```
Platforms and evaluation systems plan and invoke different harnesses behind one
typed surface, then consume stable evidence contracts. Use the `fabric` CLI or
committed JSON Schemas to validate packages and build language bindings.

Harness installation and credential requirements differ by adapter. The
[repository quick start](https://github.com/NVIDIA/NeMo-Fabric#quick-start-hermes)
contains the complete Hermes environment recipe.
## Choose Your Interface

Refer to the [Python SDK guide](/nemo/fabric/sdk/python-sdk) for planning,
diagnostics, typed requests, and multi-turn runtime examples.
Use the following table to choose the NeMo Fabric interface that best fits how
your application works with harnesses:

## Choose your interface

| Interface | Use it when | Start with |
| Interface | Use It When | Start With |
| --- | --- | --- |
| Python SDK | Your application owns job config, runtime lifecycle, or multi-turn state | [Client API](/reference/api/python-library-reference/client) |
| Runtime API | You need multiple ordered turns over one live harness runtime | [Runtime](/reference/api/python-library-reference/runtime) |
Expand All @@ -135,46 +93,46 @@ Use `agent.yaml` when the agent package is the portable artifact. Use
`FabricConfig` when a platform already owns a larger job or deployment object
and wants to pass only its NeMo Fabric slice in memory.

## Core workflow
## Core Workflow

NeMo Fabric is organized around one flow from configuration to normalized
evidence:

```text
Application or evaluation harness
|
| Python SDK or `fabric` CLI
v
NeMo Fabric Rust core
config -> plan -> lifecycle
|
| resolved adapter contract
v
Hermes Agent | Codex SDK | custom harness
|
v
RunResult + artifacts + events + telemetry references
```

1. **Configure** an agent package or typed `FabricConfig` with a harness adapter,
environment, models, tools, skills, MCP, and telemetry.
2. **Create variants** from deep copies to vary harness, model, environment, or
observability settings without mutating the base config. File-backed
packages may instead apply ordered profiles.
observability settings without mutating the base config. File-backed packages
can instead apply ordered profiles.
3. **Plan and diagnose** to resolve the adapter and check capabilities and
requirements before spending work on a runtime.
4. **Run or start a runtime** through the shared start, invoke, and stop
lifecycle contract.
5. **Consume evidence** from `RunResult`: output, structured failure details,
artifacts, events, and telemetry references.

## Next steps
## Learn More

<CardGroup cols={2}>
<Card
title="Client API"
href="/reference/api/python-library-reference/client"
>
Resolve, plan, diagnose, run, and start stateful runtimes.
</Card>
<Card
title="Runtime"
href="/reference/api/python-library-reference/runtime"
>
Invoke multiple ordered turns and stop runtime handles safely.
</Card>
<Card
title="Types"
href="/reference/api/python-library-reference/types"
>
Explore all mutable config objects and immutable request, plan, result,
artifact, telemetry, and runtime models.
</Card>
<Card
title="Errors"
href="/reference/api/python-library-reference/errors"
>
Handle config, capability, lifecycle, state, and native-extension failures.
</Card>
</CardGroup>
Continue exploring NeMo Fabric through these resources.

- **Installation** — [Installation](/getting-started/install) to set up the runtime and adapters.
- **Quickstart** — [Quickstart](/getting-started/quick-start) to build from source and run the SDK example.
- **Beginner Tutorial** — [Beginner Tutorial](/getting-started/quickstart) to run a simple agent end to end.
- **Python SDK** — [Python SDK](/nemo/fabric/sdk/python-sdk) for planning,
diagnostics, typed requests, and multi-turn runtimes.
- **API Reference** — [Client API](/reference/api/python-library-reference/client) to resolve, plan, diagnose, run, and start stateful runtimes.
2 changes: 1 addition & 1 deletion docs/about-nemo-fabric/release-notes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ description: "Release notes for NVIDIA NeMo Fabric."
{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0 */}

To be filled out at release time
Release notes for NVIDIA NeMo Fabric aren't available yet.
136 changes: 136 additions & 0 deletions docs/getting-started/beginner-tutorial.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
---
title: "NVIDIA NeMo Fabric Beginner Tutorial"
sidebar-title: "Beginner Tutorial"
description: "Learn how to configure and run a simple agent with NVIDIA NeMo Fabric."
template-library-version: "1.0.0"
---
{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0 */}

This tutorial guides you through installing NeMo Fabric, configuring its core
objects, and running a simple Hermes-backed agent.

<Card>

**Goal**: Understand how a Fabric configuration connects an agent harness to a
model, and run your first agent.

**In this tutorial, you will**:

1. Install NeMo Fabric with Hermes Agent support.
2. Configure a harness and model through typed Python objects.
3. Run an agent and inspect its response.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
</Card>

## Prerequisites

Before you begin, ensure that you have:

- Python 3.11–3.13. Hermes Agent does not currently support Python 3.14.
- An NVIDIA API key from [`build.nvidia.com`](https://build.nvidia.com/).

If you prefer the shortest path from a source checkout to a working result,
complete the [Quickstart](/getting-started/quick-start) instead.

## Concepts Overview

The example uses four core objects:

- `Fabric` runs the configured agent.
- `FabricConfig` combines the metadata, harness, and model configuration.
- `HarnessConfig` selects the agent harness and controls how NeMo Fabric
resolves it.
- `ModelConfig` selects the model provider, model, and credentials.

## Tutorial Steps

Complete each step in order and verify the result before continuing.

### Install NeMo Fabric

Create a Python virtual environment and install NeMo Fabric with Hermes Agent and the Hermes Agent adapter.

```bash
python -m venv .venv
source .venv/bin/activate
pip install "nemo-fabric[hermes, runtime]"
```

Refer to [the installation guide](https://github.com/NVIDIA/NeMo-Fabric#installation) for more details.

### Configure the API Key

Export your NVIDIA API key for the NVIDIA-hosted model used in this tutorial:

```bash
export NVIDIA_API_KEY=...
```

### Configure and Run a Simple Agent

Create a file named `beginner_tutorial.py` with the following code. Read the
configuration from the outside in: `FabricConfig` identifies the run, selects
Hermes Agent as the harness, and assigns an NVIDIA-hosted model as the default.

```python
import asyncio

from nemo_fabric import (
Fabric,
FabricConfig,
HarnessConfig,
MetadataConfig,
ModelConfig,
)

config = FabricConfig(
metadata=MetadataConfig(
name="quickstart-agent"
),
harness=HarnessConfig(
adapter_id="nvidia.fabric.hermes",
resolution="preinstalled",
settings={
"base_url": "https://integrate.api.nvidia.com/v1",
"max_iterations": 1,
},
),
models={
"default": ModelConfig(
provider="nvidia",
model="nvidia/nemotron-3-nano-30b-a3b",
temperature=0.0,
api_key_env="NVIDIA_API_KEY",
)
},
)

fabric = Fabric()
result = asyncio.run(fabric.run(config, input="Who are you?"))
print(result.output.response)
```

Run the file:

```bash
python beginner_tutorial.py
```

The tutorial is successful when the command prints the agent's response.

A more detailed version of this example is available as a [Jupyter Notebook](https://jupyter.org/)
at [`examples/notebooks/01_quickstart.ipynb`](https://github.com/NVIDIA/NeMo-Fabric/blob/main/examples/notebooks/01_quickstart.ipynb).

## Summary

You have now:

- Installed the NeMo Fabric runtime and Hermes Agent adapter.
- Configured the harness and model through typed Python objects.
- Run an agent and inspected its response.

## Next Steps

Refer to the [Python SDK guide](/nemo/fabric/sdk/python-sdk) for planning,
diagnostics, typed requests, and multi-turn runtime examples.
Loading