> This page is for NeMo Fabric, version Latest (v0.7.0) (default).
> For other versions, use one of these documentation indexes:
> - Latest (v0.7.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.7.0: https://docs.nvidia.com/nemo/fabric/v0.7.0/llms.txt
> - v0.6.1: https://docs.nvidia.com/nemo/fabric/v0.6.1/llms.txt
> - v0.6.0: https://docs.nvidia.com/nemo/fabric/v0.6.0/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/llms.txt.

# Configure Agents

> Configure agents with typed Python models and check harness compatibility.

For examples that reuse `config`, start with [Start With One Run](/nemo/fabric/sdk/python-sdk#start-with-one-run).

## Configure Agents In Code

### Normalized Configuration Compatibility

NeMo Fabric-owned fields such as workspace, environment variables, and the
invocation deadline apply to every local adapter. Adapter-translated fields are
validated against the selected adapter descriptor during planning.

`Core` means NeMo Fabric owns the behavior and applies it uniformly before or
around adapter execution. `Yes` means the adapter translates the normalized
field into its harness. `No` means an explicitly configured value fails
planning instead of being ignored. The following table groups provider-specific
Relay subfields:

| `FabricConfig` Field                                                  | Claude                                                                                                           | Codex                                                                                               | Deep Agents                                                                                         | Hermes Agent                                                                                      | mini-SWE-agent                             |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `schema_version`                                                      | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `metadata.name`, `.description`                                       | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `harness.adapter_id`, `.resolution`                                   | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `harness.settings`                                                    | Closed adapter schema                                                                                            | Closed adapter schema                                                                               | Closed adapter schema                                                                               | Closed adapter schema                                                                             | Closed `timeout` schema                    |
| `workflow.target_id`, `.settings`                                     | No                                                                                                               | No                                                                                                  | No                                                                                                  | No                                                                                                | No                                         |
| `models.<role>.provider`                                              | `anthropic` uses native auth; custom names require an Anthropic Messages-compatible `base_url` and `api_key_env` | `openai` uses native auth; custom names require a Responses-compatible `base_url` and `api_key_env` | Dynamic LangChain provider; custom OpenAI-compatible endpoints require `base_url` and `api_key_env` | Dynamic Hermes provider                                                                           | Configured provider                        |
| `models.<role>.model`                                                 | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| `models.<role>.api_key_env`                                           | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| `models.<role>.base_url`                                              | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| `models.<role>.temperature`                                           | No                                                                                                               | No                                                                                                  | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| `models.<role>.settings.<key>`                                        | No keys declared                                                                                                 | No keys declared                                                                                    | No keys declared                                                                                    | No keys declared                                                                                  | No keys declared                           |
| `models.<role>.top_p`, `.max_tokens`                                  | No                                                                                                               | No                                                                                                  | Yes                                                                                                 | Yes                                                                                               | Yes; passed through LiteLLM                |
| `instructions.system`                                                 | `replace`, `append`                                                                                              | `replace`; maps to Codex base instructions                                                          | `replace`                                                                                           | `replace`                                                                                         | `replace`                                  |
| `runtime.input_schema`, `.output_schema`                              | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `runtime.artifacts`, `.timeout_seconds`, `.response_limits`           | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `runtime.max_turns`                                                   | Yes                                                                                                              | No                                                                                                  | Yes; maps to LangGraph supersteps                                                                   | Yes; maps to Hermes iterations                                                                    | Yes                                        |
| `environment.provider`, `.control_location`, `.ownership`             | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `environment.workspace`, `.artifacts`, `.env`, `.env_names`           | Core                                                                                                             | Core                                                                                                | Core                                                                                                | Core                                                                                              | Core                                       |
| `environment.connection`, `.metadata`, `.settings`                    | Environment-provider-owned                                                                                       | Environment-provider-owned                                                                          | Environment-provider-owned                                                                          | Environment-provider-owned                                                                        | Environment-provider-owned                 |
| `tools.definitions`                                                   | No                                                                                                               | No                                                                                                  | Yes; `kind: python` LangChain tools                                                                 | No                                                                                                | No                                         |
| `tools.enabled`, `.blocked`                                           | Yes                                                                                                              | No                                                                                                  | Yes                                                                                                 | Yes; native selectors are Hermes toolset names                                                    | No                                         |
| `skills.paths`                                                        | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | No                                         |
| `skills.directories`, `.duplicates`                                   | No                                                                                                               | No                                                                                                  | Yes; refer to [Configure Skills](/nemo/fabric/integrations/harness-integrations/configure-skills)   | Yes; refer to [Configure Skills](/nemo/fabric/integrations/harness-integrations/configure-skills) | No                                         |
| `skills.bundled`                                                      | No                                                                                                               | No                                                                                                  | No                                                                                                  | Yes; refer to [Configure Skills](/nemo/fabric/integrations/harness-integrations/configure-skills) | No                                         |
| `mcp.servers.<name>.transport`, `.url` with `harness_native` exposure | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | No                                         |
| `mcp.servers.<name>.allowed_tools`, `.blocked_tools`                  | No                                                                                                               | No                                                                                                  | No                                                                                                  | No                                                                                                | No                                         |
| `mcp.servers.<name>.exposure = "fabric_managed"`                      | No; not implemented                                                                                              | No; not implemented                                                                                 | No; not implemented                                                                                 | No; not implemented                                                                               | No                                         |
| `telemetry.providers.relay`                                           | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| `telemetry.providers.native`                                          | No                                                                                                               | Yes; OpenTelemetry                                                                                  | Yes; OpenTelemetry and OpenInference                                                                | No                                                                                                | No                                         |
| `telemetry.providers.<provider>.config`                               | Declared-provider pass-through                                                                                   | Declared-provider pass-through                                                                      | Declared-provider pass-through                                                                      | Declared-provider pass-through                                                                    | Declared-provider pass-through             |
| `relay.project`, `.output_dir`, `.observability`                      | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| `relay.components`, `.policy`                                         | Yes                                                                                                              | Yes                                                                                                 | Yes                                                                                                 | Yes                                                                                               | Yes                                        |
| Other additive `extensions` on typed config objects                   | Rejected unless declared by the descriptor                                                                       | Rejected unless declared by the descriptor                                                          | Rejected unless declared by the descriptor                                                          | Rejected unless declared by the descriptor                                                        | Rejected unless declared by the descriptor |

Model selection is deterministic: the `default` role wins; otherwise a single
named role is selected. More than one role without `default` fails planning.
All bundled adapters except Hermes publish a descriptor-owned `model_schema`
for every configured model role. The Claude and Codex native providers
(`anthropic` and `openai`, respectively) keep the existing authentication path.
Other Claude and Codex providers remain valid only with an explicit `base_url`
and `api_key_env`. Deep Agents keeps dynamic LangChain provider selection. Each
published schema rejects undeclared `ModelConfig.settings` during planning and
reports each issue through `doctor(...)` before adapter startup. Existing
configurations that supplied `top_p` and `max_tokens` as flattened model
extensions retain the same wire shape when loaded as normalized fields. Legacy
adapter descriptors that accept either name through `extension_schemas.model`
continue receiving it in `AgentModelConfig.extensions`; adapters that advertise
the normalized capability receive the typed field instead.

Descriptors can also declare a `config_schema` for static requirements spanning configuration blocks. Both `plan(...)` and metadata-only `inspect_adapter(...)` enforce these requirements. The shared NOOA adapter requires a registered workflow. Deep Agents requires an explicit `tools.enabled` allowlist (including `[]`) or `execute` in `tools.blocked` when `local_shell` is selected. Cline's `model_schema` rejects the `openai` provider alias; its pinned SDK uses `openai-native`, and the documented NVIDIA endpoint uses `nvidia`. Planning does not prove native package availability, authentication, endpoint health, or membership in Pi's installed model catalog.

If a normalized field has no complete mapping, `plan(...)` and runtime start
fail with a configuration compatibility error naming the adapter and field.
`doctor(...)` retains the incompatibility and returns a failed diagnostic check
so callers can inspect all preflight findings. NeMo Fabric does not silently
drop the field. `runtime.max_turns` is optional, so a config that omits it
remains portable across adapters with different native turn-limit support.

Build the complete nested `FabricConfig` directly, or start with a base
config and use helpers to add capabilities. For example, extend the config from
the first example with skills, MCP, and telemetry:

```python
capability_config = config.model_copy(deep=True)
capability_config.add_skill_path("./skills/code-review")
capability_config.add_mcp_server(
    "github",
    transport="stdio",
    url="github-mcp",
    args=["stdio"],
    env={"GITHUB_TOKEN": "${GITHUB_TOKEN}"},
    exposure="harness_native",
)
capability_config.enable_relay(
    project="fabric-review",
    output_dir="./artifacts/relay",
)
```

### Configure Skills

`SkillConfig` holds the `skills` section. It has the following fields:

| Field         | Type                                                 | Default | Meaning                                                                                                                                  |
| ------------- | ---------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `paths`       | `list[str \| Path]`                                  | `[]`    | Skill paths. Each adapter defines what a path means.                                                                                     |
| `directories` | `list[SkillDirectory] \| None`                       | `None`  | Structured entries, each naming one skill or a folder of skills. Set only when `paths` is empty. `[]` loads no external skills.          |
| `bundled`     | `BundledSkills \| None`                              | `None`  | Which skills that ship with the harness load. `None` keeps the harness default.                                                          |
| `duplicates`  | `"reject"`, `"first_wins"`, `"last_wins"`, or `None` | `None`  | What happens when two `directories` entries supply skills with the same name. Requires `directories`. `None` keeps the harness behavior. |

`SkillDirectory` sets exactly one of `skill`, a folder that holds `SKILL.md`, or `folder`, a folder of skills. `BundledSkills` has `enabled` (default `True`), `include`, and `exclude`. `include` and `exclude` cannot both be set, and `enabled=False` takes neither list. For both lists, `None` and `[]` mean different things.

The following example loads a folder of skills and one more skill, leaves out one bundled skill, and lets the later entry win a name clash:

```python
from nemo_fabric import BundledSkills, SkillConfig, SkillDirectory

skills_config = config.model_copy(deep=True)
skills_config.skills = SkillConfig(
    directories=[
        SkillDirectory(folder="./skills"),
        SkillDirectory(skill="/mnt/release-review"),
    ],
    bundled=BundledSkills(exclude=["github-auth"]),
    duplicates="last_wins",
)
```

Relative paths resolve against `base_dir`. `add_skill_path(path)` adds to `paths`, so it raises `ValueError` when `directories` is set; add a `SkillDirectory` entry instead. `remove_skill_path(path)` removes the `skills` section only when nothing else in it is set.

`directories`, `bundled`, and `duplicates` need an adapter whose descriptor advertises them. Planning rejects them otherwise. Refer to [Configure Skills](/nemo/fabric/integrations/harness-integrations/configure-skills) for start checks, the `output.skills` run report, and harness differences.

### Set Environment Values Or Forward Them By Name

Use `environment.env` to set literal values. Use `environment.env_names` to forward variables that are already available to the NeMo Fabric process.

| Field       | What You Supply                                          | What NeMo Fabric Saves In The Config And Run Plan |
| ----------- | -------------------------------------------------------- | ------------------------------------------------- |
| `env`       | A name and its literal value, such as `LOG_LEVEL: debug` | The name and value                                |
| `env_names` | A name, such as `GITHUB_TOKEN`                           | Only the name                                     |

For example, set `GITHUB_TOKEN` in the shell that launches your application:

```bash
export GITHUB_TOKEN="example-token"
```

Then extend the configuration with a literal log level and the token's name:

```python
from nemo_fabric import EnvironmentConfig

config.environment = EnvironmentConfig(
    env={"LOG_LEVEL": "debug"},
    env_names=["GITHUB_TOKEN"],
)
```

NeMo Fabric looks up `GITHUB_TOKEN` in its own process environment and passes the actual value, `example-token`, to the adapter in `RuntimeContext.environment.env`. The adapter receives the value, not a name that it must look up. The configuration and run plan contain only the name; NeMo Fabric redacts environment values in the saved adapter invocation. Execution fails if a listed variable is unset. A name cannot appear in both `env` and `env_names`.

`environment.env` does not expand `$GITHUB_TOKEN` or `${GITHUB_TOKEN}`. For example, `env={"GITHUB_TOKEN": "$GITHUB_TOKEN"}` passes the literal text `$GITHUB_TOKEN`. Use `env_names=["GITHUB_TOKEN"]` to request lookup. If your application instead reads the token and places its value in `env`, that value becomes part of the saved configuration and run plan.

A `.env` file stores names and values, such as `GITHUB_TOKEN=example-token`. Neither `env` nor `env_names` loads that file. Your launcher or application must load it into the process environment before NeMo Fabric starts the adapter. The same forwarding mechanism works with variables supplied by a shell, CI secrets, or a container.

With Harbor, the NeMo Fabric process runs inside the task environment. `env_names` reads that process's variables; listing a name does not copy its value from the Harbor host into the task. Harbor owns delivery through its managed execution environment. The existing Harbor bridge uses a separate `environment_env_names` payload field and resolves those names into `environment.env` inside the task runner. That bridge behavior is unchanged by `env_names`. Refer to [Harbor Environment Forwarding](/nemo/fabric/integrations/consumer-integrations/harbor#environment-forwarding) for the two-stage flow.

NeMo Fabric reads named values at adapter start and checks them before each invocation. Persistent harnesses and shell backends can retain their startup environment, so NeMo Fabric rejects an invocation if a named value has changed instead of sending a context that disagrees with that environment. The error identifies the variable without exposing its value. Restart the runtime and any associated service after changing a forwarded value. Connecting a new runtime to a service also fails if the named values differ from the service's startup values.

### Configure MCP Authentication And Headers

MCP authentication and custom-header support vary by adapter:

| Adapter      | OAuth 2.0 (`oauth2`) | Client credentials (`service_account`) | HTTP `custom_headers` |
| ------------ | -------------------- | -------------------------------------- | --------------------- |
| Claude       | Unsupported          | Unsupported                            | Supported             |
| Codex        | Supported            | Unsupported                            | Supported             |
| Deep Agents  | Unsupported          | Supported                              | Supported             |
| Hermes Agent | Supported            | Unsupported                            | Supported             |

An adapter returns a configuration error when `authentication` uses a type it
does not support.

Configure OAuth 2.0 with `McpAuthenticationConfig`. The adapter and MCP server
complete the authorization flow before the first agent turn. The flow can
require interactive browser authorization.

```python
from nemo_fabric import McpAuthenticationConfig

capability_config.add_mcp_server(
    "github",
    transport="streamable-http",
    url="https://mcp.example.com/mcp",
    authentication=McpAuthenticationConfig(
        type="oauth2",
        scopes=["repo:read"],
    ),
    exposure="harness_native",
)
```

Configure OAuth 2.0 client credentials with `type="service_account"` when the
agent calls an MCP server as its own service identity, with no user and no
browser. `client_secret_env` names the environment variable that holds the
client secret; the configuration contains only the name. Use a separate Deep Agents configuration, which supports this authentication type. Install the [Deep Agents runtime and adapter](/nemo/fabric/integrations/harness-integrations/lang-chain-deep-agents#install-the-adapter), set `NVIDIA_API_KEY` and `JIRA_MCP_CLIENT_SECRET` in the launching environment, and replace the example MCP/token URLs and client ID with your service's values:

```python
from nemo_fabric import (
    FabricConfig,
    HarnessConfig,
    McpAuthenticationConfig,
    MetadataConfig,
    ModelConfig,
    ToolsConfig,
)

service_account_config = FabricConfig(
    metadata=MetadataConfig(name="service-account-agent"),
    harness=HarnessConfig(adapter_id="nvidia.fabric.langchain.deepagents"),
    models={
        "default": ModelConfig(
            provider="openai",
            model="nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
            base_url="https://integrate.api.nvidia.com/v1",
            api_key_env="NVIDIA_API_KEY",
        )
    },
    tools=ToolsConfig(blocked=["execute"]),
)
service_account_config.add_mcp_server(
    "jira",
    transport="streamable-http",
    url="https://jira-mcp.example.com/mcp",
    authentication=McpAuthenticationConfig(
        type="service_account",
        client_id="fabric-agent",
        client_secret_env="JIRA_MCP_CLIENT_SECRET",
        token_url="https://auth.example.com/oauth2/token",
        scopes=["jira.read"],
    ),
)
```

The adapter requests a token from `token_url`, sends it as
`Authorization: Bearer <token>` with every MCP request, and requests a new one
before it expires. `token_endpoint_auth_method` selects `client_secret_basic`
(the default) or `client_secret_post`, and `token_cache_buffer_seconds` (300 by
default) sets how early the token is renewed. `service_account` applies to
`sse` and `streamable-http` servers. Startup fails if the variable named by
`client_secret_env` is unset, if `token_url` or the server `url` is not `https`
(plain `http` is accepted only for a loopback host), if the transport is
`websocket`, or if the same server sets an `Authorization` custom header.

Some MCP servers sit behind a gateway and need two tokens: the
`service_account` bearer token admits the agent to the server, and a second
token, sent in its own header, selects the identity used for the system behind
the server. That second token can belong to a service account in that system or
to a user, so the agent sees what that account can see. Combine
`service_account` with a `custom_headers` entry that references an environment
variable. Create a gateway-only variant of the Deep Agents configuration so it does not inherit the preceding Jira server. Set `GATEWAY_CLIENT_SECRET` and your downstream token before starting this variant:

```python
import os

from nemo_fabric import McpConfig

os.environ["DOWNSTREAM_TOKEN"] = "..."  # issued by the downstream system

gateway_config = service_account_config.model_copy(deep=True)
gateway_config.mcp = McpConfig()
gateway_config.add_mcp_server(
    "bugs",
    transport="streamable-http",
    url="https://mcp-gateway.example.com/bugs/mcp",
    authentication=McpAuthenticationConfig(
        type="service_account",
        client_id="fabric-agent",
        client_secret_env="GATEWAY_CLIENT_SECRET",
        token_url="https://auth.example.com/oauth2/token",
        scopes=["bugs"],
    ),
    custom_headers={"X-Downstream-Token": "${DOWNSTREAM_TOKEN}"},
)
```

Only the `service_account` token is requested and renewed by the adapter. The
second token is sent as configured, so replace the variable and restart the
runtime when it expires. Set the variable before starting the runtime: an
empty value fails startup with `AdapterConfigError`, and an unset variable is
not expanded, so the literal `${DOWNSTREAM_TOKEN}` text is sent. A rejected
second token does not stop the server's tools from loading: the gateway
accepts the bearer token, and the error appears in the tool result when the
downstream system refuses the call.

Use `custom_headers` to send HTTP headers with an `sse` or `streamable-http`
server. Header names and values must be valid HTTP header text. To provide a
sensitive value, set it in the process environment and use a `${NAME}`
reference in the header value:

```python
import getpass
import os

os.environ["MCP_ACCESS_TOKEN"] = getpass.getpass("MCP access token: ")

capability_config.add_mcp_server(
    "private-api",
    transport="streamable-http",
    url="https://mcp.example.com/mcp",
    authentication=None,
    custom_headers={
        "Authorization": "Bearer ${MCP_ACCESS_TOKEN}",
        "X-Tenant": "example-team",
    },
)
```

Set referenced environment variables before calling `run(...)` or
`start_runtime(...)`. Do not use `McpServerConfig.env` for HTTP header
variables; `env` applies only to `stdio` MCP server processes.

> **Warning**
>
> The Claude adapter stages its MCP configuration in a file for the Claude SDK.
> A sensitive value in `custom_headers` can therefore be written to
> disk. Store sensitive values in environment variables and use `${NAME}` in
> `custom_headers`. The adapter stages the reference and supplies the value
> through the scoped child-process environment instead of writing the value to
> the MCP configuration file.

MCP tool policy is scoped to one server and uses the tool names that server
advertises. `allowed_tools=None` exposes every discovered tool, while an empty
allowlist exposes none. `blocked_tools` is then removed from the allowed or
discovered set, and the same tool cannot appear in both lists:

```python
capability_config.add_mcp_server(
    "github",
    transport="streamable-http",
    url="${GITHUB_MCP_URL}",
    exposure="harness_native",
    allowed_tools=["issues.read", "pull_requests.read"],
    blocked_tools=["issues.delete"],
)
```

An adapter must declare both `mcp` and `mcp.tool_filters` support before
planning accepts these fields. The bundled adapters currently support
unfiltered MCP servers only. Per-server MCP policy is distinct from the root
`ToolsConfig`, which controls adapter-native tools across the harness.
An MCP server requiring authentication also requires `mcp.auth.oauth2` or
`mcp.auth.service_account`, matching its configured authentication type.

`tools.definitions` names tools and tool groups that the adapter constructs.
Each definition has a portable `kind`, an adapter-resolved `ref`, and settings
validated by the adapter descriptor. Use `add_tool_definition(...)` only when
the selected adapter accepts `tools.definitions` and publishes a
`tool_definition_schema`.

`tools.enabled` and `tools.blocked` select across the effective named tool
surface. Configure an allowlist, a blocklist, or both:

```python
from nemo_fabric import ToolsConfig

def with_tool_policy(base):
    tool_config = base.model_copy(deep=True)
    tool_config.tools = ToolsConfig(
        enabled=["file", "terminal"],
        blocked=["web"],
    )
    return tool_config
```

`tools.enabled=None` preserves the harness default. An empty list disables every
executable tool. A tool cannot appear in both lists. The selected adapter must
enforce the complete configured policy or planning fails. Hermes interprets
these adapter-native selectors as Hermes toolset names.

Config helpers edit the typed config before planning or starting a runtime.
They do not modify already-started runtimes. Use `block_tools(...)`,
`remove_mcp_server(name)`, and `remove_skill_path(path)` to edit a copied config.
Telemetry is enabled by adding entries to `telemetry.providers`; settings
specific to NeMo Relay live in the top-level `relay` block.

For evaluation or deployment variations, use ordinary Python functions and
copies of the typed config. Supply the complete final config to NeMo Fabric.

```python
def review_agent_config(base, *, github_mcp: bool, relay: bool):
    config = base.model_copy(deep=True)
    if github_mcp:
        config.add_mcp_server(
            "github",
            transport="streamable-http",
            url="${GITHUB_MCP_URL}",
            exposure="harness_native",
        )
    if relay:
        config.enable_relay(project="fabric-review", output_dir="./artifacts/relay")
    return config

variant = review_agent_config(config, github_mcp=True, relay=True)
```

NeMo Relay observability is represented directly in the SDK config's top-level
`relay` block. Configure ATOF file and stream sinks as follows:

```python
from nemo_fabric import (
    RelayAtofConfig,
    RelayAtofFileSinkConfig,
    RelayAtofStreamSinkConfig,
    RelayObservabilityConfig,
)

relay_config = config.model_copy(deep=True)
relay_config.enable_relay(
    output_dir="./artifacts/relay",
    observability=RelayObservabilityConfig(
        atof=RelayAtofConfig(
            enabled=True,
            sinks=[
                RelayAtofFileSinkConfig(
                    output_directory="./artifacts/relay",
                    filename="events.atof.jsonl",
                    mode="overwrite",
                ),
                RelayAtofStreamSinkConfig(
                    name="nemo-fabric-stream",
                    url="http://localhost:4319",
                    transport="ndjson",
                ),
            ],
        ),
    ),
)
```

To write OpenTelemetry spans to local files, add `file_sinks` to the `opentelemetry` section. File sinks need NeMo Relay 0.10 or later. You can use them instead of endpoints or alongside them. When `opentelemetry` is enabled, it needs at least one endpoint or file sink.

The following example writes OpenInference spans to files instead of sending them to a collector:

```python
relay_config.enable_relay(
    output_dir="./artifacts/relay",
    observability={
        "opentelemetry": {
            "enabled": True,
            "file_sinks": [
                {"type": "openinference", "output_directory": "./artifacts/relay"}
            ],
        },
    },
)
```

NeMo Fabric handles these files as follows:

* As with ATOF and ATIF files, each runtime writes to its own directory: `<output_directory>/<runtime_id>`. If you omit `output_directory`, NeMo Fabric uses `artifacts/relay`.
* If you omit `filename`, Relay names each file with a timestamp when it starts. A later invocation can then write to a new file.
* File sinks append by default. If you set `filename`, that file keeps the spans from earlier invocations. To replace it each time Relay starts, set `"mode": "overwrite"`.
* `RunResult.artifacts` lists each file as an artifact of kind `otlp`. Its media type is `application/x-ndjson` for the default `json_lines` format and `application/x-protobuf` for the `proto` format.

Relay buffers spans and writes them in batches. It writes the final batch when it shuts down, so read the files after the runtime stops. If Relay crashes, or is forcibly stopped because it does not shut down in time, a file can be missing its most recent spans.

`RelayAtifConfig.model_name` is an optional ATIF-only override. When you omit
it, NeMo Fabric writes the selected `default` model, or the only configured
model, into the Relay plugin configuration. If `config.models` is empty, the
resolved configuration uses `"unknown"`, matching the adapter fallback.
Multiple model roles without `default` fail planning before telemetry
resolution.
The derived label preserves `ModelConfig.model` exactly, including provider
prefixes such as `openai/gpt-5-codex`. Adapter-specific wire-model translation
does not change this telemetry label. Set the override explicitly only when the
trajectory must use a different label.

Additional NeMo Relay plugin components can be supplied generically with
`RelayComponentConfig` when their component package is available in the runtime
environment.

The repository's
[code-review example](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/examples/code_review_agent)
uses this pattern for complete Hermes Agent, Codex, Deep Agents,
environment, MCP, and telemetry variants.

If a config contains relative paths, pass a `base_dir` to `plan(...)`,
`doctor(...)`, `run(...)`, `prepare_service(...)`, `attach_service(...)`, or
`start_runtime(...)`. The base directory anchors skills, workspaces, artifacts,
and other relative paths to the caller's package or job layout.

### Configure Dynamic Relay Plugins

Dynamic Relay plugins are configured separately under `relay.plugins.dynamic`. Enable `telemetry.providers.relay` with `enable_relay()` so NeMo Fabric forwards this configuration to the adapter's Relay integration. The following example configures a dynamic plugin without static components:

```python
from nemo_fabric import RelayConfig

plugin_config = config.model_copy(deep=True)
plugin_config.relay = RelayConfig(
    plugins={
        "dynamic": [
            {
                "manifest": "/opt/switchyard/relay-plugin.toml",
                "enabled": True,
            }
        ]
    }
)
plugin_config.enable_relay()
```

NeMo Fabric preserves the `relay.plugins` section alongside any configured `relay.observability`, `relay.components`, and `relay.policy`. Relay owns manifest validation, loading, and activation. Use absolute manifest paths accessible inside the agent environment. Plugin activation depends on the selected adapter's Relay integration and the installed Relay version. For Hermes installation requirements, refer to [Use the Hermes Agent Adapter](/nemo/fabric/integrations/harness-integrations/hermes-agent).

## Feature Support Across Harness Adapters

The SDK presents one consistent shape across adapters, but adapters differ in
their runtime requirements, accepted configuration, and optional capabilities.

Use `plan(...)` and `doctor(...)` before relying on optional features:

```python
fabric = Fabric()
plan = fabric.plan(config)
report = await fabric.doctor(config)

print(plan.adapter.adapter_id)
print(report.status)
```

Use the plan to confirm adapter selection and capability routing. Use the doctor
report to catch unresolved adapter descriptors, unsupported normalized
capabilities, missing declared requirements, and environment problems before
starting a runtime.

Capability routes assign execution ownership; they do not describe network
routing. `harness_native` means the selected adapter executes the capability
through its harness. `fabric_managed` means NeMo Fabric executes it outside the
harness-native surface. `unsupported` means neither side can execute it.
Routes apply to tools, skills, and MCP servers. Scalar fields such as
`instructions.system` and `runtime.max_turns` are validated separately against
the adapter descriptor.

## Custom Fields And Adapter Settings

Use normalized NeMo Fabric fields for portable behavior: models, system
instructions, turn limit, runtime, environment, skills, MCP, telemetry, tools,
and artifacts.

Supply request context through `RunRequest.context` for each invocation. Request
context is not part of `FabricConfig`.

Use `harness.settings` only for stable, harness-native behavior declared by the
selected descriptor. Each bundled adapter declares a closed settings schema.
Executable paths, Relay command discovery, state directories, and similar
launch mechanics are runtime implementation details rather than public adapter
settings.

Use the optional `workflow` block to select a registered target by `target_id`
and provide its immutable construction settings. The Adapter Target Descriptor
selects the adapter, supplies the target-native entry point, and validates
`workflow.settings` during planning. Fabric then projects the entry point and
settings into `AgentConfig.workflow`; consumer configuration does not repeat
adapter-specific entry-point semantics. Validation does not apply schema
defaults.

Use `FabricConfig.metadata` for human-readable agent identity and caller-owned
annotations. NeMo Fabric preserves these values in the resolved configuration
but does not copy them into `RunResult.metadata`. Use `request_id` and
`RunRequest.context` for per-invocation correlation. `RunResult.metadata`
contains adapter-specific result details.

To group several invocations into one NeMo Relay session, set
`RunRequest.relay_session_root` to the same UUID string on each
invocation. Deep Agents and mini-SWE-agent, which own an in-process Relay Agent
scope, use it as the propagated Relay root. A UUID `request_id` stays the
parent; otherwise the session root is also the parent. ATIF exports one
trajectory per invocation under one `session_id`. An unusable value falls back
to the per-request root without an error, and the invocation still succeeds. A
context key named `session_id` does not group traces.

For example, invoke each turn with `RunRequest(input=message, relay_session_root=conversation_uuid)`. Core forwards the typed field as `AgentRunRequest.relay_session_root`. Context keys do not control Relay grouping. Omitting the field preserves per-request behavior. Use matching runtime and adapter-contract versions when sending this field.

Adapter settings are not portable by default. The exact descriptor selected
during planning owns their JSON Schema. Planning and doctor reject settings
that do not satisfy that schema. A descriptor without `settings_schema` accepts
an empty settings map and rejects a non-empty map. Validation does not apply
schema defaults or otherwise change the settings preserved in `RunPlan`.
Validation errors identify the adapter, descriptor source and path, and
offending settings path.