Skip to navigation

Stage 1: Describe the Adapter

View as MarkdownOpen in Claude

An Adapter Descriptor tells NVIDIA NeMo Fabric how to locate an adapter and which contract surface it implements. NeMo Fabric reads and validates this record during planning without importing or starting the adapter.

Adapter Descriptor filenames end in .fabric-adapter.json.

Prerequisites

Before you start, complete the following:

  1. Read the Adapter Contract overview to understand where the descriptor sits in the six-stage authoring flow.
  2. Choose the runtime binding your adapter uses: python, process, http, or native_plugin.
  3. Keep the canonical adapter-descriptor.schema.json open for exact fields, defaults, and constraints.

Concepts Overview

The primary descriptor fields are:

FieldPurpose
contract_versionSelects the complete negotiated adapter contract. Use fabric.adapter/v1alpha2.
adapter_idIdentifies the adapter implementation during selection and planning.
adapter_kindSelects the runtime binding: python, process, http, or native_plugin.
runnerSupplies binding-specific startup metadata, such as a Python module.
requirementsDescribes binaries, environment-variable names, files, services, or plugin hooks for diagnostics.
configDeclares the normalized fields the adapter applies and target-native files it generates.
capabilitiesDeclares optional runtime operations implemented through the adapter binding.
telemetryDeclares telemetry outputs and integration modes the adapter produces or forwards.
skillsDeclares the structured skill features the adapter implements: skills.directories loading, bundled-skill selection, and duplicate policies.
target_typesDeclares registered target types a shared adapter can load. Omit it for a direct harness or dedicated-agent adapter.
Keep Claims Exact

Declare only behavior implemented through the adapter boundary. A target’s native cancellation or streaming feature does not become a NeMo Fabric capability until the adapter binding implements the corresponding contract. Relay-backed ATOF streaming does not require capabilities.streaming; that flag is reserved for the optional native OpenAI streaming operation.

To Implement the Adapter Descriptor

Work through each step in order, verifying your progress at each checkpoint.

1. Create a Minimum Descriptor

The following descriptor is enough to declare an in-process Python adapter that accepts an empty AgentConfig and implements only the required lifecycle:

{
"contract_version": "fabric.adapter/v1alpha2",
"adapter_id": "com.acme.fabric.example",
"adapter_kind": "python",
"runner": {
"module": "acme_fabric_adapter.runtime"
}
}

Use a globally stable adapter_id. Treat it as a machine identifier, not a display name. Adapters receive AgentConfig; FabricConfig never crosses the southbound boundary.

Success Check: Planning can read and validate the descriptor’s metadata without importing or starting the adapter.

2. Declare Accepted Configuration

Add a config.accepts value only after the implementation applies that field. For example, the following adapter accepts named models, model endpoints, system instructions, and a target-applied turn limit:

"config": {
"accepts": [
"models",
"models.base_url",
"instructions.system",
"runtime.max_turns"
],
"system_instruction_modes": ["replace", "append"]
}

Accepting a parent does not automatically accept every optional child. For example, models accepts the base model block, while models.temperature and models.base_url are separate declarations. Use the schema enum for the exact accepted values.

Planning rejects configured normalized behavior outside the declared surface. NeMo Fabric does not silently remove unsupported fields.

Accept runtime.keep_state only when the adapter keeps all of its native state in RuntimeContext.state_dir when that field is present. Every runtime of the agent then receives the same folder, so a later runtime finds the earlier runtime’s sessions, memory, and other harness files. On Linux and macOS, the adapter host inherits the folder’s lock. Detached children with inherited lock descriptors can keep the state locked after the host exits and prevent later runtimes from starting. A detached child without the lock can outlive the host and access the state folder after another runtime acquires the lock. Ensure that all children stop accessing retained state before the lock is released.

When an adapter accepts instructions.system, declare the exact supported modes in config.system_instruction_modes. replace discards the harness default system instruction. append preserves the harness default and adds the configured content after it. New descriptors must declare the supported modes explicitly. For compatibility with descriptors created before mode discovery, an omitted system_instruction_modes value means replace only.

Mode declarations must be nonempty, unique, and accompanied by instructions.system in config.accepts. Planning rejects an unsupported configured mode at instructions.system.mode before the adapter starts.

Success Check: A configured field outside config.accepts fails planning instead of being silently ignored.

3. Declare Structured Skill Support

An adapter that lists skills in config.accepts receives skills.paths. The structured fields skills.directories, skills.bundled, and skills.duplicates need a top-level skills block. Each sub-block is optional. Leave out a sub-block when the adapter does not implement that feature. Planning rejects a configured field that needs a missing sub-block and names the field.

The following block declares support for all three features:

"skills": {
"directory_loading": {
"supported_entries": ["skill", "folder"],
"skill_file": "SKILL.md",
"discovery": {
"traversal": "recursive",
"nested_skills": "stop_at_skill",
"depth_limit": {"kind": "fixed", "levels": 6}
},
"parsing": {
"required_frontmatter_fields": ["description"],
"name_fallback": "directory_name",
"frontmatter_errors": "reject"
}
},
"bundled": {
"default": "enabled",
"supports_enable": true,
"supports_disable": true,
"supports_include": true,
"supports_exclude": true
},
"duplicates": {
"supported_policies": ["reject", "first_wins", "last_wins"],
"native": "The harness keeps the first copy it finds.",
"name_source": "frontmatter"
}
}

The sub-blocks describe what the adapter implements, not settings a caller chooses:

FieldMeaning
directory_loading.supported_entriesThe entry kinds the adapter loads: skill, folder, or both. Non-empty and unique.
directory_loading.skill_fileThe file that marks a skill folder. Must be SKILL.md.
directory_loading.discovery.traversalimmediate_children searches only the folder’s direct children. recursive searches every level.
directory_loading.discovery.nested_skillsinclude also finds skills inside a skill’s folder. stop_at_skill stops at a skill’s folder.
directory_loading.discovery.depth_limitRequired. {"kind": "fixed", "levels": N} with N at least 1, where the configured folder is depth 0. {"kind": "no_fixed_limit"} has no depth cap, but exclusions still apply. {"kind": "adapter_defined"} means the adapter documents its own bounds.
directory_loading.parsing.required_frontmatter_fieldsFront-matter fields a skill must have to load. Can be empty.
directory_loading.parsing.name_fallbackdirectory_name uses the folder name when the front matter has no name. none skips the skill.
directory_loading.parsing.frontmatter_errorsrecover_key_value recovers simple key: value lines. reject rejects a skill whose front matter does not parse. adapter_defined means the adapter documents its own handling.
bundled.defaultWhat loads when skills.bundled is left out: enabled, disabled, or none when the harness ships no bundled skills.
bundled.supports_enable, .supports_disable, .supports_include, .supports_excludeWhich skills.bundled requests the adapter implements, including the empty-list meaning of include and exclude. All four are required.
duplicates.supported_policiesThe skills.duplicates values the adapter implements. Non-empty and unique.
duplicates.nativeOptional. A short description of what the harness does when skills.duplicates is left out.
duplicates.name_sourceOptional. Whether names are compared by frontmatter name or by directory name.

Every field in directory_loading is required, so a descriptor cannot claim unlimited discovery by accident. Declare a value only after the adapter implements it. Refer to Configure Skills for the behavior callers see.

Success Check: A configured skills.directories, skills.bundled, or skills.duplicates value that the skills block does not cover fails planning with the field path.

4. Add Adapter-Owned Schemas

Use an Adapter Descriptor schema for target-specific data that cannot be validated by the normalized contract alone:

Descriptor FieldValidates
config_schemaStatic cross-field constraints on the serialized FabricConfig, including workflow selection and conditional tool policy.
settings_schemaFabricConfig.harness.settings for this adapter.
model_schemaEvery configured model role, including provider compatibility and closed model settings.
tool_definition_schemaEvery normalized named tool or tool-group definition.
extension_schemasAdapter-owned data at named southbound extension points.

Use config_schema for requirements that span configuration blocks. For example, a shared adapter can declare {"type": "object", "required": ["workflow"]}. Planning and host metadata inspection apply this schema before installation or startup. It supplements the normalized contract and the other descriptor schemas; it does not grant support for fields missing from config.accepts. Leave unrelated top-level fields open so the schema does not duplicate the evolving northbound contract. Model extensions use their serialized, flattened northbound names in this schema.

Keep installed-package availability, native catalog lookup, credentials, network access, and dynamic target state in startup validation. Successful planning establishes declared configuration compatibility, not runtime health. Keep references local to each schema object.

The following closed settings schema permits one optional command timeout:

"settings_schema": {
"type": "object",
"properties": {
"command_timeout": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": false
}

Use a closed object with no properties when the adapter accepts harness.settings but has no settings. Omit the schema when the adapter does not support that configuration surface.

Schemas must be valid, self-contained JSON Schema objects. NeMo Fabric does not load arbitrary HTTP or file references during planning. Use additionalProperties: false unless an intentionally open compatibility surface is part of the adapter contract.

Success Check: Each declared schema is a self-contained JSON Schema object with no external references.

5. Register Targets for a Shared Adapter

A shared framework adapter separates its static implementation descriptor from the custom agents it can load. The Adapter Descriptor declares the supported target type:

{
"contract_version": "fabric.adapter/v1alpha2",
"adapter_id": "com.acme.fabric.framework",
"adapter_kind": "python",
"target_types": ["workflow"],
"runner": {
"module": "acme_framework_adapter.runtime"
},
"config": {
"accepts": ["models", "tools.definitions"]
}
}

Each separately installed workflow publishes one *.fabric-target.json Adapter Target Descriptor. The target record selects its adapter, fixes the adapter-scoped entry point, and validates that target’s workflow settings:

{
"contract_version": "fabric.adapter/v1alpha2",
"type": "workflow",
"id": "com.acme.email-phishing",
"adapter_id": "com.acme.fabric.framework",
"spec": {
"entrypoint": {
"kind": "factory",
"ref": "acme.agent.react"
},
"settings_schema": {
"type": "object",
"properties": {
"llm_name": {
"type": "string",
"minLength": 1
}
},
"required": ["llm_name"],
"additionalProperties": false
}
}
}

The Adapter Target Descriptor uses the same contract_version as the Adapter Descriptor. It does not introduce another contract or schema version. workflow.target_id selects the target by id; consumer configuration does not repeat its adapter-specific entry point.

Use the canonical adapter-target-descriptor.schema.json for the complete target record.

Success Check: Planning resolves a workflow.target_id to exactly one registered target that names this adapter.

Summary

In this tutorial, you have:

  • Created a minimum Adapter Descriptor that NeMo Fabric validates during planning without importing adapter code.
  • Declared the normalized configuration surface your adapter applies through config.accepts and system_instruction_modes.
  • Declared the structured skill features your adapter implements in the skills block.
  • Added adapter-owned JSON Schemas for target-specific data.
  • Registered targets so a shared framework adapter can load separately installed custom agents.

Next Steps

With the descriptor in place, continue through the adapter authoring stages:

Local shutdown budget

Local Python and process adapters have a 10-second stop exchange budget by default. An adapter descriptor can set runner.stop_timeout_seconds to an integer from 1 through 300 when native shutdown requires more time. The value applies to that adapter’s runtimes and services. Include the adapter’s cleanup time in the budget. OpenClaw declares 30 seconds to allow its 15-second graceful shutdown and remaining cleanup.