> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/overview/llms.txt. # NVIDIA NeMo Fabric Adapter Contract An adapter makes an agent harness or custom agent available through the same NVIDIA NeMo Fabric configuration, lifecycle, and result APIs. Fabric consumers can then change Adapter Targets without adding target-specific launch and control code to every application, evaluator, or rollout system. An **Adapter Target** is the harness, framework, custom agent, or remote service behind an adapter. The adapter translates the NeMo Fabric contract into that target's native configuration and execution model. ## Why Build an Adapter A Fabric-ready Adapter Target gains the following benefits: - One consumer-facing `FabricConfig` and runtime lifecycle - Compatibility checks before target code starts - Isolated, ordered runtime state - Normalized failures, artifacts, results, and telemetry references - Optional NeMo Relay streaming without a target-specific streaming method The adapter remains small because NeMo Fabric owns planning, environment preparation, adapter selection, correlation, and consumer-facing enrichment. The adapter owns only target translation, target state, invocation, and cleanup. The following diagram shows the adapter contract flow from consumer planning through the adapter and Adapter Target to the consumer result: ```mermaid flowchart TD Consumer["Consumer
FabricConfig + RunRequest"] Planning["NeMo Fabric planning
discover | resolve | validate | project"] Adapter["Adapter
AgentConfig + AgentRunRequest + RuntimeContext
start | invoke | stop"] Target["Adapter Target
harness | shared framework | custom agent"] Result["Consumer result
RunResult + artifacts + telemetry refs"] Consumer --> Planning --> Adapter --> Target Target --> Adapter --> Result Planning --> Result ``` ## Choose an Integration Shape Use the narrowest reusable adapter boundary that your target provides: | Integration Shape | Use It When | Adapter Reuse | Reference | | --- | --- | --- | --- | | Harness adapter | An opinionated harness supplies a stable construction and execution model. | One adapter supports many configurations of that harness. | [Hermes Agent](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/adapters/python/hermes); [mini-SWE-agent](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/adapters/python/mini-swe-agent) for the minimum surface | | Shared framework adapter | A framework can load multiple registered custom agents through stable entry-point semantics. | One adapter supports many separately installed targets. | [NeMo Agent Toolkit](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/external/nat) | | Dedicated custom-agent adapter | The application owns execution behavior that does not fit a reusable loading contract. | One adapter packages one custom agent or agent family. | [LangGraph email-phishing analyzer](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/examples/langgraph_custom_agent) | A custom agent does not automatically need a dedicated adapter. A shared adapter is appropriate when a framework has stable loading and invocation semantics. Use a dedicated adapter when the agent itself is the only clear execution boundary. Refer to [Custom Agents](/nemo/fabric/adapter-contract/custom-agent-integrations) for the decision model. Use Hermes Agent as the primary harness-adapter reference. Start with mini-SWE-agent when implementing a first adapter: it intentionally keeps the required descriptor, configuration translation, and lifecycle surface small. ## Implement the Minimum Surface The minimum local adapter has four parts: 1. One discoverable `*.fabric-adapter.json` descriptor. 2. `start`, which initializes one isolated target runtime from `AgentConfig`. 3. `invoke`, which executes exactly one request and returns one terminal `AgentRunResult`. A runtime can perform zero or more ordered `invoke` operations. 4. `stop`, which attempts cleanup after successful, partial, or failed work. The minimum profile permits one active invocation per runtime. It does not require an adapter-managed queue, concurrent turns, native streaming, cancellation, or live updates. Consumers create independent Fabric runtimes for parallel work. `Runtime.invoke_stream()` also does not add an adapter method. The adapter runs ordinary `invoke` while NVIDIA NeMo Relay supplies correlated Agent Trajectory Observability Format (ATOF) records to the consumer. ## Build in Stages Follow these stages in order and stop when the target has the behavior it needs: | Stage | Add | Done When | | --- | --- | --- | | 1. [Describe the adapter](/nemo/fabric/adapter-contract/tutorials/describe-adapter) | Identity, runtime binding, minimum descriptor, and optional target records. | NeMo Fabric can discover and validate metadata without importing adapter code. | | 2. [Map configuration](/nemo/fabric/adapter-contract/tutorials/map-normalized-configuration) | Only the normalized `AgentConfig` fields and typed settings the target applies. | Unsupported behavior fails planning instead of being ignored. | | 3. [Implement execution](/nemo/fabric/adapter-contract/tutorials/implement-execution) | `start`, `invoke`, `stop`, runtime isolation, and safe failures. | One runtime can execute an ordered request sequence and always attempts cleanup. | | 4. [Normalize outcomes](/nemo/fabric/adapter-contract/tutorials/normalize-results-and-telemetry) | `AgentRunResult`, error translation, artifacts, and telemetry integration. | Every completed target invocation has one safe terminal outcome. | | 5. [Package and register](/nemo/fabric/adapter-contract/tutorials/register-and-discover-adapter) | Installed descriptor files or explicit development paths. | Planning resolves the intended adapter and optional registered target by exact ID. | | 6. [Verify the adapter](/nemo/fabric/adapter-contract/tutorials/verify-adapter) | Planning, lifecycle, cleanup, isolation, and declared capability tests. | The minimum profile and every descriptor claim have evidence. | Add [native OpenAI Chat Completions streaming](/nemo/fabric/adapter-contract/optional-openai-streaming) only after the required lifecycle works. It is an optional adapter capability and is independent of Relay-backed ATOF streaming. ## Use the Published Contract The repository documentation and versioned schemas are the source of truth. Use examples to understand the boundary, but do not recreate types from an example: - [`schemas/adapter-contract/`](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/schemas/adapter-contract) contains the canonical JSON Schemas. - `nemo-fabric-adapter-contract` provides dependency-free Python dataclasses with optional Pydantic interoperability. - The TypeScript `nemo-fabric-adapter-contract` package provides generated compile-time types and bundles the JSON Schemas for runtime validation. - [`nemo-fabric-build-adapter`](https://github.com/NVIDIA/NeMo-Fabric/blob/v0.7.0/skills/nemo-fabric-build-adapter/SKILL.md) is the public coding-agent skill for adapter authoring. - [Examples and References](/nemo/fabric/adapter-contract/examples-and-references) identifies the exact files to read for each integration shape. The current contract version is `fabric.adapter/v1alpha2`. The same `contract_version` covers Adapter Descriptors, Adapter Target Descriptors, `AgentConfig`, `RuntimeContext`, and the negotiated lifecycle binding. Adapter package versions are independent implementation-release versions. ## Docs - [1. Describe the Adapter](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/tutorials/describe-adapter.md) - [2. Map Normalized Configuration](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/tutorials/map-normalized-configuration.md) - [3. Implement Execution](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/tutorials/implement-execution.md) - [4. Normalize Results and Telemetry](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/tutorials/normalize-results-and-telemetry.md) - [5. Register and Discover the Adapter](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/tutorials/register-and-discover-adapter.md) - [6. Verify the Adapter](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/tutorials/verify-adapter.md) - [Custom-Agent Integrations](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/custom-agent-integrations.md) - [Optional Native OpenAI Streaming](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/optional-openai-streaming.md) - [Examples and References](https://docs.nvidia.com/nemo/fabric/v0.7.0/adapter-contract/examples-and-references.md)