> This page is for NeMo Fabric, version v0.7.0.
> 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.

# Hermes SDK

> Invoke the embedded Hermes agent with normalized configuration and results.

Start with [hermes.mdx](/nemo/fabric/integrations/harness-integrations/hermes-agent) for shared setup and an overview of all four invocation paths.

NVIDIA NeMo Fabric's Hermes SDK path executes requests through an embedded Hermes `AIAgent` in the adapter host. It returns normalized results and reuses conversation history across ordered invocations.

## Installation

Complete the [shared installation](/nemo/fabric/integrations/harness-integrations/hermes-agent#install-the-adapter). The SDK path requires no interface-specific packages or frontend builds. Install any additional dependencies required by your selected tools and MCP servers in the Hermes adapter environment.

## Configure the Adapter

Use normalized `FabricConfig` fields for the model, instructions, tools, skills, MCP servers, workspace, turn limit, and telemetry. Use `harness.settings` for Hermes-specific options and native interface selection.

The following example configures an embedded SDK agent with file tools:

```python
from nemo_fabric import FabricConfig

config = FabricConfig.from_mapping(
    {
        "metadata": {"name": "hermes-agent"},
        "harness": {
            "adapter_id": "nvidia.fabric.hermes",
        },
        "models": {
            "default": {
                "provider": "openai",
                "model": "your-model",
                "base_url": "https://MODEL_HOST/v1",
                "api_key_env": "MODEL_API_KEY",
                "temperature": 0.0,
                "top_p": 0.9,
                "max_tokens": 1024,
            }
        },
        "instructions": {
            "system": {"mode": "replace", "content": "Help with files in the workspace."}
        },
        "tools": {"enabled": ["file"], "blocked": ["terminal"]},
        "runtime": {"max_turns": 8},
        "environment": {"provider": "local", "workspace": "."},
    }
)
```

Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter environment before starting. To add native API or browser access, follow the [Hermes invocation paths](/nemo/fabric/integrations/harness-integrations/hermes-agent).

The following rules apply to the normalized configuration:

* **System instructions:** Only `instructions.system.mode: replace` is supported.
* **Tools:** Selectors are Hermes toolset names.
* **Turn limit:** Use `runtime.max_turns` to control the agent loop.

### Hermes Settings

The descriptor uses closed schemas, so unknown settings are rejected.

| Setting                               | Default                                   | Behavior                                                                                                                                                                                                             |
| ------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sdk.enabled`                         | `true`                                    | Initialize the embedded SDK agent. Set to `false` for native-only execution; enable at least one native interface. SDK invocation then fails with `hermes_sdk_disabled`, while runtime management remains available. |
| `reasoning_config`                    | `{"effort": "none"}`                      | Optional `enabled` boolean and `effort`: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`.                                                                                                                     |
| `plugins`                             | None                                      | Plugins by source, `bundled.entries` and `external`; refer to [Plugins](/nemo/fabric/integrations/harness-integrations/hermes-agent#plugins). Configure NeMo Relay through NeMo Fabric telemetry settings.           |
| `plugins_enabled`                     | `[]`                                      | Native Hermes plugin identifiers to enable.                                                                                                                                                                          |
| `save_trajectories`                   | `false`                                   | Save native JSONL trajectories; separate from normalized telemetry.                                                                                                                                                  |
| `max_tokens`                          | Hermes native default                     | Response-token limit used when the selected model has no explicit `max_tokens`. A model-level limit takes precedence; if both are omitted, Hermes uses its native default.                                           |
| `terminal_timeout`                    | `60`                                      | Positive timeout in seconds for a Hermes terminal tool operation; this does not enable a TUI.                                                                                                                        |
| `auxiliary.title_generation.enabled`  | Hermes native default; `false` with Relay | Automatic session-title generation. An explicit value wins over the Relay default.                                                                                                                                   |
| `auxiliary.background_review.enabled` | Hermes native default                     | Automatic background memory and skill review after turns.                                                                                                                                                            |
| `tools.tool_search.enabled`           | Hermes native default                     | Native tool search: `auto`, `on`, `off`, `true`, or `false`. Separate from the normalized top-level `tools` selectors.                                                                                               |

The `auxiliary` and `tools` settings apply to all four paths; refer to [Native Harness Controls](/nemo/fabric/integrations/harness-integrations/hermes-agent#native-harness-controls).

Use the [API](/nemo/fabric/integrations/harness-integrations/hermes-api), [dashboard](/nemo/fabric/integrations/harness-integrations/hermes-dashboard), or [terminal TUI](/nemo/fabric/integrations/harness-integrations/hermes-terminal-tui) guide for native interface selection.

## Invoke and Stream

Start the runtime with the configured Hermes interpreter. With `config` from the preceding example, invoke it through the public SDK:

```python
from nemo_fabric import Fabric

async with await Fabric().start_runtime(config) as runtime:
    result = await runtime.invoke(input="List the files in the workspace.")
    print(result.output)
```

`Runtime.invoke_stream()` uses Relay-backed event streaming; retrieve its normalized result with `stream.result()`. Refer to [streaming](/nemo/fabric/sdk/streaming#nemo-relay-streaming) for the SDK usage pattern.

## Lifecycle and Conversations

The embedded SDK agent is enabled by default and initializes during runtime startup, together with its parent session database and SDK-owned MCP connections. SDK initialization errors remain startup errors.

The runtime starts even when some configured MCP servers are unavailable. Hermes Agent connects each server separately at startup and keeps the tools of the servers that connected. Each result from that runtime lists the servers Hermes Agent currently reports as failed under `output.mcp.unavailable_servers`, with the server `name`, `transport` and `reason` (`failed`). The adapter also writes a warning to standard error when a server first becomes unavailable. The list reflects Hermes Agent's state after each turn: a server that has since connected, or that is still connecting, is not listed, and each new runtime connects every server again. Hermes Agent records only an error message for a failed connection, and error messages are not reported because they can contain URLs, headers or other credentials, so entries have no `error_type` and timeouts are reported as `failed`. Invalid server configuration, such as an unsupported transport or authentication mode, still fails startup, and an OAuth server that cannot be authenticated still fails the invocation.

Ordered SDK invocations reuse the same agent and conversation until stop closes them. API, browser, and terminal conversations do not execute through this agent or inherit its live history. Use a saved `SessionRef` and retained storage to select the same SDK conversation in a replacement runtime.

Set `harness.settings.sdk.enabled` to `false` only when at least one native interface is enabled. Disabling the embedded Hermes agent does not affect runtime management: your application can still start, check, and stop the native interfaces through the NeMo Fabric SDK. SDK invocation returns a failed `RunResult` with the stable error code `hermes_sdk_disabled` and `retryable: false`. This is a configuration mismatch: enable the SDK agent before invoking through the SDK. The native interfaces and their health checks remain available.

Evaluation consumers, including Harbor, must keep `sdk.enabled: true` (or omit `sdk`). A native-only configuration is for hosting interfaces; it cannot run SDK evaluation trials. Current adapter metadata and `RunPlan` do not expose this invocation restriction before startup, so metadata-based admission can accept a configuration whose trials will fail. Exposing this restriction before invocation is planned work.

## Results and Relay

SDK invocations return normalized NeMo Fabric `RunResult` objects. With Relay enabled, the adapter finalizes and flushes available ATOF/ATIF evidence before returning the result. Native interface responses remain native; see the [normalization comparison](/nemo/fabric/integrations/harness-integrations/hermes-agent#what-nemo-fabric-normalizes).

## Health and Limitations

Whenever the SDK agent is enabled, `check()` supports `live`, `active`, and `ready` using SDK session/database ownership, the invocation interface, and fresh `get_activity_summary()` diagnostics. This includes mixed runtimes: SDK activity remains `idle` or `busy`, and a separate API or TUI process failure does not fail SDK runtime health. SDK activity does not describe native conversations.

With `sdk.enabled: false`, checks observe the enabled native processes and endpoints, with activity reported as `unknown`. Check native endpoints or interface logs separately to diagnose a native interface in a mixed runtime; a normalized interface health target is planned under [#566](https://github.com/NVIDIA/NeMo-Fabric/issues/566). Checks do not run an agent turn.

Refer to [SDK health checks](/nemo/fabric/sdk/health-checks) and the [shared limitations](/nemo/fabric/integrations/harness-integrations/hermes-agent#limitations-and-planned-work).

## Resume a Saved SDK Conversation

Enable `runtime.keep_state` and retain the full artifact directory. Save the `SessionRef` returned at startup in caller-owned storage. Pass the saved reference when starting a replacement runtime:

```python
from nemo_fabric import Fabric, SessionRef

config.runtime.keep_state = True
config.runtime.artifacts = "artifacts"
fabric = Fabric()

async with await fabric.start_runtime(config) as first:
    saved_reference = first.session_ref.to_mapping()
    await first.invoke(input="Remember the deployment target is staging.")

async with await fabric.start_runtime(
    config, session_ref=SessionRef.from_mapping(saved_reference)
) as resumed:
    result = await resumed.invoke(input="Which deployment target did we choose?")
```

The replacement gets a new runtime identifier and restores the selected native conversation. Omitting `session_ref` starts a fresh conversation. A corrected agent name can use the saved reference within the same retained storage. The reference must match the resolved adapter.

Hermes applies its native resume checks, saved prompt, tool selection, and compression history. A missing or incompatible session produces a structured error. If `recovery_warnings` reports an uncertain earlier turn, inspect native and external state before sending a new request with `acknowledge_recovery=True`. NeMo Fabric preserves the conversation, including unfinished requests. The model may act on those requests after acknowledgment. The caller decides whether to continue with that history.

`SessionRef` resume requires `sdk.enabled: true`, which is the default. `RunPlan.capabilities.session_resume` reports the adapter's declared capability. A native-only runtime can retain its Hermes home with `runtime.keep_state` and start without issuing a session reference. Hermes rejects explicit SDK session selection in native-only mode with `session_resume_unsupported` before native startup. API, browser, and terminal conversations use Hermes's native selection behavior. See the [SDK resume contract](/nemo/fabric/sdk/requests-and-runtimes#resume-a-hermes-conversation) for storage and recovery details.