/nemo-fabric-build-adapter

name: nemo-fabric-build-adapter
description: Build, migrate, review, and maintain third-party NVIDIA NeMo Fabric adapters against the public adapter contract. Use when creating adapter or target descriptors, mapping AgentConfig into an agent harness or custom-agent runtime, implementing start/invoke/stop, declaring schemas and capabilities, packaging discovery metadata, or assessing adapter conformance. Do not use for consumer applications that only call the NVIDIA NeMo Fabric SDK.

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](https://github.com/NVIDIA/NeMo-Fabric/tree/main/docs/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](https://github.com/NVIDIA/NeMo-Fabric/tree/main/schemas/adapter-contract) 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.

• 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, environm