Stage 2: Map Normalized Configuration
Consumers describe intent with FabricConfig. During planning, NVIDIA NeMo
Fabric resolves descriptors, validates compatibility, and projects only the
configuration that the selected adapter declared into AgentConfig.
Adapters consume AgentConfig. They do not parse FabricConfig or
consumer-owned planning fields.
Prerequisites
Before you start, complete the following:
- Complete Stage 1: Describe the adapter so the
descriptor declares, through
config.accepts, the fields this stage projects. - Identify which
AgentConfigblocks your adapter needs and applies. - Keep the canonical
agent-config.schema.jsonopen for exact fields and constraints.
Concepts Overview
Planning resolves consumer intent into the adapter-facing AgentConfig:
The smallest valid AgentConfig is empty. Add a block only when the adapter
needs and applies it.
AgentConfig contains these adapter-facing blocks:
Use the canonical
agent-config.schema.json
for exact fields and constraints. Python adapters can use the matching
dependency-free dataclasses from nemo_fabric_adapter_contract.models.
To Map the Normalized Configuration
Work through each step in order, verifying your progress at each checkpoint.
1. Project Only Supported Fields
The Adapter Descriptor, capability plan, and optional Adapter Target Descriptor control projection. Planning applies these rules:
- Use
config.acceptsto gate adapter-applied model configuration, system instructions, maximum turns, tool definitions, enabled tools, and blocked tools. - Validate every configured model role against
model_schemawhen the descriptor supplies one. - Validate
harness.settingsagainst the Adapter Descriptor’ssettings_schema, then project the validated settings when present. - Validate
workflow.settingsagainst the selected Adapter Target Descriptor, then project that target’s entry point intoworkflow. - Validate every named tool definition against
tool_definition_schema. - Project skills and MCP servers assigned to the adapter by the capability
plan. Project
skills.directories,skills.bundled, andskills.duplicatesonly when the descriptor’sskillsblock covers them. - Validate adapter-owned extensions against the schema for their exact extension point.
- Reject configured behavior that the selected adapter cannot apply.
Unsupported behavior fails planning with a field path and reason. It is never silently dropped.
An absent optional field can preserve the target’s default. An explicitly
empty value can mean something different. For example,
tools.enabled: null preserves the target’s native selection, while
tools.enabled: [] explicitly selects no named tools.
Success Check: A configured field the descriptor does not accept fails planning with a field path and reason instead of being silently dropped.
2. Apply System Instructions Explicitly
An omitted instructions.system value preserves the harness’s native system
instruction. When a system instruction is present, mode defaults to
replace for compatibility:
replacereplaces the harness’s native system instruction withcontent.appendpreserves the harness’s native system instruction and addscontentafter it.
The selected Adapter Descriptor must accept instructions.system. When its
config.system_instruction_modes capability list is present, the list must
declare the selected mode. An omitted list preserves compatibility with legacy
descriptors and supports replace only. Planning and doctor(...) reject
unsupported modes at instructions.system.mode. Adapters must also validate
the mode at their direct startup boundary so callers that host an adapter
without NeMo Fabric planning receive the same fail-closed behavior.
Success Check: An unsupported instructions.system.mode is rejected both
during planning and at the adapter’s direct startup boundary.
3. Keep Fabric-Owned Context Out of AgentConfig
AgentConfig does not contain adapter selection, installation policy,
environment ownership, invocation deadlines, artifact manifests, or planning
diagnostics. NeMo Fabric also resolves telemetry and Relay configuration
outside AgentConfig. When enabled, RuntimeContext.telemetry supplies the
adapter with the generated Relay configuration path, environment overlay, and
telemetry metadata needed for the invocation.
Credential fields contain environment-variable names, not resolved secret
values. Environment values can be available in
RuntimeContext.environment.env. Never persist or log the unredacted context.
Success Check: AgentConfig carries no adapter selection, deadlines,
artifact manifests, or resolved secret values.
4. Translate Once at the Boundary
Keep translation in a small adapter-owned function. The following
representative code assumes the adapter’s documented consumer configuration
requires a model named default, then resolves that model and the system
instruction into target-native values:
The descriptor must accept every field used by this translation. Do not read
undeclared values defensively or fall back to parsing the original
FabricConfig.
Success Check: The translation reads only descriptor-accepted fields and
never falls back to parsing FabricConfig.
5. Use Extensions Deliberately
Use an extension only when a normalized field cannot express the behavior:
- Define a typed model for the adapter-owned data.
- Publish its JSON Schema in
AdapterDescriptor.extension_schemasat the exact extension point, such asmodel,mcp_server,workflow, orrun_result. - Set the value through the corresponding block’s
extensionsmap or helper. - Reject data when the descriptor does not declare that extension point or the value does not satisfy its schema.
Do not use an extension to disguise an unsupported normalized field. An extension is adapter-specific unless multiple adapters intentionally implement the same namespaced contract.
Success Check: Each extension value is validated against a declared extension-point schema and rejected when the point is not declared.
6. Split Static and Startup Validation
Planning validates static shape and compatibility without executing adapter
code. During start, the adapter validates only requirements that depend on
the target environment, such as imports, installed factories, executable
presence, credential availability, and service reachability. Report the
failing requirement or configuration field without exposing secret values.
Success Check: Planning validates static shape without running adapter
code, while environment-dependent checks run during start.
7. Check Skill Directories at Start
AgentConfig.skills can carry these fields:
A non-empty paths never arrives together with directories. The folders in
directories exist only in the task environment, so check them in start.
Python adapters can use the dependency-free
nemo_fabric_adapter_contract.skills module. The following example raises
a lifecycle failure through the optional common Python host from
Stage 3:
load_directories() follows the rules that callers see:
-
It checks each entry in list order. A missing path fails with
not_found. A path that is not a folder or cannot be accessed, askillentry without a readableSKILL.md, and afolderentry that cannot be listed fail withinvalid.SkillLoadError.fieldnames the failing key, such asskills.directories[1].skill. -
It finds skills inside each
folderentry by theDiscoveryRules. Make these rules match the descriptor’sdirectory_loadingblock, and match what the harness actually loads:folder_root_is_skill: the harness loads aSKILL.mdat the root of afolderentry as a skill.support_dir_names: folders the harness does not search inside a skill, such asscripts.allow_symlink_escape=False: the harness refuses a skill whose real path is outside the entry. Such a skill is skipped withpath_escape.subroot_depths: a root child, such asskills, that the harness searches to a different depth than the rest of the entry.skill_marker="any_entry": the harness treats any entry namedSKILL.md, even a folder or a broken link, as marking a skill, so discovery stops there. The reader then decides whether it loads. The default,"file", needs aSKILL.mdfile.
When entries need different rules, pass a function of the entry’s index, kind, and resolved path as
rules.DiscoveryRulesdescribe only the folders the harness searches, not how it readsSKILL.md. -
It passes every candidate folder to one call of
reader, aCandidateReader. The reader returns aCandidateInfo(name, valid, reason, name_uncertain)for each folder:name: the name the harness reads, orNonefor the folder name fallback.valid:Truewhen the harness loads the skill,Falsewhen it refuses it, orNonewhen the reader can’t tell.reasonis required withFalseand becomes the skip reason. Useunreadablefor aSKILL.mdthat can’t be read; askillentry like that fails withinvalid.name_uncertain:Truewhen the reader can’t tell the harness’s name.
The helper module stays dependency-free, so it doesn’t parse YAML. Pass a reader backed by the harness’s own parser, so that names and refusals match what the harness loads. The default
front_matter_reader()reads only a single-linename:value, plain or quoted, and marks other namesname_uncertain. Withrequired_fields, it refuses a skill that lacks a top-level key, with the reasonmissing_frontmatter_field:<key>. -
It skips refused candidates before any duplicate check, and records skipped candidates and empty
folderentries instead of failing. Under an explicitduplicatespolicy, an uncertain name fails withunsupported_frontmatter_name, and a skill withvalid=Nonefails withunsupported_frontmatterwhen the policy’s result depends on it. -
It applies the
duplicatespolicy between entries. With a policy set, two skills with the same name inside onefolderentry fail withduplicate, even when another entry also reaches one of them. With no policy, it records each clash asambiguous.
Pass the selected skills to the harness’s native skill loader.
DirectoryLoad.selected lists the skills that load. With an explicit policy,
pass each selected skill’s folder, so that shadowed copies never load.
Apply bundled with the harness’s native controls, and fail start when an
include or exclude name is not a bundled skill. Return
report_block(load, bundled=...) as output.skills in each result. When the
adapter can tell every skill its harness loads, also pass the bundled and
local ones as LoadedSkill items in other_loaded, so that loaded lists
them all. Refer to
Configure Skills for the full
behavior.
Success Check: A missing skills.directories path fails start with the
entry’s field, and each result reports the loaded skills under
output.skills.
Summary
In this tutorial, you have:
- Projected only descriptor-accepted fields into
AgentConfig. - Applied system instructions with explicit, validated modes.
- Kept Fabric-owned context and resolved secrets out of
AgentConfig. - Translated configuration once at the adapter boundary.
- Used extensions only where a normalized field cannot express the behavior.
- Split static planning validation from environment-dependent startup checks.
- Checked
skills.directoriesentries in the task environment at start.
Next Steps
With configuration mapping defined, continue through the adapter authoring stages: