Build an NVIDIA NeMo Fabric Adapter

Build against the published southbound contract. Keep the adapter thin: let NeMo Fabric own planning and consumer-facing behavior, and let the adapter own only target translation and lifecycle state.

Read the Contract

Read the current adapter contract before changing code. Start with the overview, choose an integration shape, then follow the numbered descriptor, configuration, execution, results, registration, and verification stages. Read the custom-agent page when the target loads application-defined agents or workflows. Read the optional native OpenAI streaming page only when the adapter claims that capability.

Use the committed adapter-contract JSON Schemas or the schemas installed with the matching NeMo Fabric release for exact wire shapes. Do not reconstruct a schema from examples or copy field lists into adapter code.

Establish the Boundary

Establish the adapter boundary before defining its descriptor:

1. Identify the adapter implementation and its stable adapter_id.
2. Choose a harness adapter, a shared framework adapter with registered targets, or a dedicated custom-agent adapter.
3. Reuse one shared adapter across custom agents when the framework provides stable loading and invocation semantics. Use a dedicated adapter when the agent itself is the only unambiguous execution boundary.
4. List the normalized fields the target can actually enforce.
5. Separate adapter-wide harness.settings, per-target workflow.settings, and typed extensions.
6. Keep installation, environment preparation, Relay orchestration, caller scheduling, and consumer result enrichment outside the adapter.

If the requested behavior cannot be expressed by the current contract, surface the gap. Do not silently consume an unsupported northbound field or hide it in an unrelated extension.

Define the Descriptor First

Create one self-contained *.fabric-adapter.json before implementing target translation:

• Set the current contract_version, a globally stable adapter_id, adapter_kind, and runner binding.
• Declare only normalized config.accepts fields the implementation enforces.
• When accepting instructions.system, declare the exact supported config.system_instruction_modes. New descriptors must not rely on the legacy omitted-value behavior, which means replace only.
• Declare mcp.auth.oauth2 or mcp.auth.service_account only when the adapter implements the corresponding MCP authentication mode.
• Publish closed settings_schema, model_schema, tool_definition_schema, and extension_schemas where applicable. Use model_schema only for static model/provider compatibility and model settings; keep credential validity and provider availability in startup validation.
• New adapters that consume models.<role>.top_p or .max_tokens should declare the corresponding normalized config.accepts field. Existing descriptors that declare either name through extension_schemas.model remain compatible and receive it in AgentModelConfig.extensions.
• Declare runtime requirements and telemetry outputs without secret values.
• Leave optional capability flags false unless the installed NeMo Fabric runtime exposes and tests that adapter operation. Set capabilities.streaming only when the adapter implements native OpenAI Chat Completions streaming through invoke_openai_stream. Relay-backed ATOF streaming is independent and does not require this capability.

If the adapter loads registered targets, list their types in target_types. Create one *.fabric-target.json per target. The target record owns its adapter_id, type-specific entry point, and workflow settings schema. It uses the same contract_version as the Adapter Descriptor.

Validate descriptor schemas without importing adapter code. Keep all schema references local to the descriptor document; do not rely on HTTP or file references.

Package Discovery Metadata

Install the descriptor in the standard shared-data location. For setuptools:

[tool.setuptools.data-files]
"share/nemo-fabric/adapters/acme" = ["acme.fabric-adapter.json"]
"share/nemo-fabric/targets/acme" = ["email.fabric-target.json"]

Depend on nemo-fabric-adapter-contract for typed standard-library dataclasses. Install its optional pydantic extra only for Pydantic interoperability. Add nemo-fabric-adapters-common only if the adapter chooses its lifecycle or Relay helpers. A bare adapter package should not depend on the NeMo Fabric runtime.

For a TypeScript adapter, depend on nemo-fabric-adapter-contract. Import descriptor, configuration, runtime-context, request, and result types from the package root, matching the Python package's single model namespace. TypeScript types do not validate data received from a process or network boundary; validate untrusted values against the JSON Schemas included with the package.

Map AgentConfig

Accept a validated AgentConfig and translate each declared field once at the adapter boundary:

• Resolve named model roles into target-native model clients or settings.
• Apply normalized instructions and runtime limits only when declared. Validate instructions.system.mode at the adapter startup boundary as well as during planning; replace discards the harness default, while append preserves it and adds the configured content after it.
• Convert MCP servers, tool definitions, tool policy, and skills into native target constructs.
• Resolve workflow entry points and construction settings during start in the task environment.
• Read identity, environment, artifacts, telemetry, and the invocation deadline (deadline_millis) from RuntimeContext, not from workflow settings.

Reject unsupported values with stable, safe error codes. Do not log complete configs, environment values, headers, credentials, or arbitrary user input.

Use typed extension models and publish their schemas at the exact descriptor extension point. Never treat extensions as an unchecked dictionary escape hatch.

Implement the Lifecycle

Implement exactly one start, zero or more ordered invoke operations, and one stop for each NeMo Fabric runtime.

• Construct and retain target state in start.
• Accept AgentRunRequest and RuntimeContext, then return one AgentRunResult from invoke.
• Make stop safe after partial startup and failed invocation.
• Isolate mutable state between independent runtimes.
• If the descriptor declares capabilities.streaming, implement async invoke_openai_stream(request, context, emit). Execute the target exactly once, await emit(chunk) only for the openai.chat_completions.chunk/v1 profile, and return one AgentRunResult. Each chunk requires non-empty id and model, a nonnegative integer created, the exact chat.completion.chunk discriminator, and structurally valid choices. An invocation that emits no chunks is valid.
• Do not add an adapter streaming method for Relay-backed Runtime.invoke_stream(); execute ordinary invoke and use the provided telemetry context.

For native OpenAI streaming, the SDK owns the authenticated loopback HTTP transport with chunked NDJSON framing. The common host validates the transport, removes its credentials from the adapter payload, and supplies the emit callback. Do not persist or log stream credentials, write chunks to stdout, add SSE framing, or forward other target-native event profiles.

For a Python adapter that opts into the common host:

from nemo_fabric_adapter_contract.models import AgentConfig
from nemo_fabric_adapter_contract.models import AgentRunRequest
from nemo_fabric_adapter_contract.models import AgentRunResult
from nemo_fabric_adapter_contract.models import AgentRunStatus
from nemo_fabric_adapter_contract.models import RuntimeContext
from nemo_fabric_adapters.common import lifecycle


class TargetRuntime:
    async def start(self, payload):
        config: AgentConfig = payload["config"]
        ...

    async def invoke(
        self,
        request: AgentRunRequest,
        context: RuntimeContext,
    ) -> AgentRunResult:
        native = await self.target.run(request.input)
        return AgentRunResult(
            status=AgentRunStatus.SUCCEEDED,
            output={"response": native.text},
        )

    async def invoke_openai_stream(self, request, context, emit):
        async for chunk in self.target.stream(request.input):
            await emit(chunk)
        return AgentRunResult(
            status=AgentRunStatus.SUCCEEDED,
            output={"response": self.target.final_text},
        )

    async def stop(self):
        ...


def main() -> None:
    lifecycle.serve(TargetRuntime, config_loader=AgentConfig.from_mapping)

The common host decodes the internal lifecycle envelope before calling the adapter and encodes its terminal result afterward. Adapter code does not parse the transport envelope or infer failure from fields inside output. Return AgentRunStatus.FAILED with an AgentRunError when the target completes with a failed outcome. Raise an exception when the adapter cannot produce a normalized terminal result.

Support Warm Session Continuation

When later invocations must use earlier conversation state, retain that state on the adapter runtime created during start. Prefer a target-native live session whose lifetime and retention behavior are suitable for the deployment. Do not substitute a framework's development-only in-memory checkpointer in a production adapter. If the target has no suitable facility, retain the adapter-owned history required to construct its next native request.

Bound retained history so a live runtime cannot grow memory or model input without limit. When consumers need control, publish a typed adapter-wide harness.settings or target-specific workflow.settings field with explicit units, defaults, validation bounds, and overflow behavior. Do not overload runtime.max_turns, which limits one invocation's agent loop.

Keep session state separate from invocation state. Conversation context, required artifact references, and live workspace state may persist until stop; timeout state, invocation counters, terminal markers, result assembly, usage, and telemetry scopes reset for each invoke. Independent runtime instances must never share mutable continuation state.

Normalize usage per invocation in AgentUsage. If the target reports cumulative session totals, retain a session-local baseline and difference successive observed counters rather than summing cumulative snapshots or using only the last model response. Missing or reset counters remain unknown. Keep the closed fabric.adapter/v1alpha2 usage fields unchanged. Put cache-write, reasoning, peak request, and per-model detail in usage.extensions["nemo_fabric.detailed_token_usage.v1"], and declare that object with extension_schemas.usage in the adapter descriptor. The detailed object repeats the normalized token counters so its inclusion flags are self-contained; input_tokens_include_cache covers both cached reads and cache writes there. NeMo Fabric preserves the object as RunResult.usage.metadata["nemo_fabric.detailed_token_usage.v1"]. Consumers treat any detailed field for an input or output dimension as selecting the detailed counters for that dimension without falling back to its top-level counters. Report the primary counter, inclusion flag, and every excluded component together so consumers can calculate an inclusive total. Preserve available usage on unsuccessful terminal results. Do not infer missing cost or promote estimates to cost_usd.

Test observable continuation rather than merely calling invoke twice: make the second result depend on the first turn without caller-side replay, then prove another runtime cannot observe that context. Refer to the LangGraph custom-agent example for an adapter-owned history pattern.

For in-process Relay SDK telemetry where the adapter owns the invocation-level Agent scope, wrap that scope with relay_request_context(context.request_id, request.relay_session_root) from nemo_fabric_adapters.common.utils. The helper uses a UUID request ID as Relay's propagated root and always returns nemo_fabric_request_id metadata, including for non-UUID request IDs. When the caller sets the typed AgentRunRequest.relay_session_root to a UUID string Relay accepts, that value becomes the root instead, a UUID request ID stays the parent (otherwise the session root is), and nemo_fabric_session_root is added to the metadata, so the caller's invocations share one Relay session. Context keys do not control propagation. An unusable session root falls back to a usable UUID request ID without raising; if neither value is usable, the helper returns nullcontext() without setting propagation. Merge nemo_fabric_adapters.common.utils.relay_correlation_metadata(context) into that metadata with metadata.update(...) rather than replacing it, so keys from relay_request_context() reach the scope. relay_correlation_metadata() returns the reserved nemo_fabric_request_id, nemo_fabric_invocation_id, and nemo_fabric_runtime_id keys that consumers use to join Relay telemetry to a NeMo Fabric result. Do not apply this pattern to an external Relay gateway or an upstream integration that creates an isolated scope context unless its boundary accepts a per-turn propagation context.

Handle Custom Agents

For a shared framework adapter, select the registered target with FabricConfig.workflow.target_id. Use the selected Adapter Target Descriptor's spec.entrypoint.kind for adapter-scoped resolution semantics and ref for the factory identity. Validate workflow.settings against that target's spec.settings_schema.

• Define only entry-point kinds that the shared adapter resolves unambiguously. The v1alpha2 contract does not define a global kind catalog.
• Map a declared factory intent to the corresponding target-native factory. The current NeMo Agent Toolkit reference maps fabric.agent.react to its ReAct workflow factory.
• Supply factories an adapter-defined build context containing already resolved native values; do not require custom agents to parse FabricConfig or AgentConfig.
• Use a dedicated adapter without an artificial workflow entry point when the selected adapter already identifies one application-owned agent.

Compare the NeMo Agent Toolkit shared adapter with the dedicated LangGraph example before choosing the custom-agent boundary.

Validate Before Handoff

Complete these checks before handing off an adapter:

1. Install the built wheel in an isolated adapter environment.
2. Confirm discovery below share/nemo-fabric and inspect the resolved adapter and target descriptors in Fabric().plan(...).
3. Exercise one accepted normalized config and rejection for unsupported fields and each declared schema.
4. Run doctor(...) with both missing and satisfied requirements.
5. Test start, success, target failure, malformed output, repeated invocation, stop, partial-start cleanup, EOF cleanup, and two-runtime isolation.
6. If native OpenAI streaming is claimed, test empty and multi-chunk streams, malformed and oversized records, invalid chunks, sequence and identity mismatches, a missing end record, early consumer close without cancellation, a separate terminal result, one active turn, and exactly one target invocation.
7. Test Relay correlation separately if telemetry support is claimed.
8. Report the adapter package version, contract version, required-profile result, and every optional capability as supported or unsupported.

Do not claim automated NeMo Fabric conformance until the published conformance suite exists and the exact adapter release passes it.

Selected Software Reports

The standard-library nemo_fabric_evidence.evidence module, also re-exported by nemo_fabric_adapter_contract.evidence, defines ExecutionEvidence and its inventory/observation types. These are shared report types; the closed AgentRunResult shape is unchanged. A caller can supply an explicit owner report through FabricConfig.provenance.reports. NeMo Fabric's shared lifecycle hosts also collect selected adapter software at initialization when provenance is enabled. Missing or invalid optional evidence must not fail an invocation. Preserve original capture time and full versions; report only selected components and existing owner reports, without new network or executable probes.