Configure Agents
For examples that reuse config, start with Start With One Run.
Configure Agents In Code
Normalized Configuration Compatibility
NeMo Fabric-owned fields such as workspace, environment variables, and the invocation deadline apply to every local adapter. Adapter-translated fields are validated against the selected adapter descriptor during planning.
Core means NeMo Fabric owns the behavior and applies it uniformly before or
around adapter execution. Yes means the adapter translates the normalized
field into its harness. No means an explicitly configured value fails
planning instead of being ignored. The following table groups provider-specific
Relay subfields:
Model selection is deterministic: the default role wins; otherwise a single
named role is selected. More than one role without default fails planning.
All bundled adapters except Hermes publish a descriptor-owned model_schema
for every configured model role. The Claude and Codex native providers
(anthropic and openai, respectively) keep the existing authentication path.
Other Claude and Codex providers remain valid only with an explicit base_url
and api_key_env. Deep Agents keeps dynamic LangChain provider selection. Each
published schema rejects undeclared ModelConfig.settings during planning and
reports each issue through doctor(...) before adapter startup. Existing
configurations that supplied top_p and max_tokens as flattened model
extensions retain the same wire shape when loaded as normalized fields. Legacy
adapter descriptors that accept either name through extension_schemas.model
continue receiving it in AgentModelConfig.extensions; adapters that advertise
the normalized capability receive the typed field instead.
Descriptors can also declare a config_schema for static requirements spanning configuration blocks. Both plan(...) and metadata-only inspect_adapter(...) enforce these requirements. The shared NOOA adapter requires a registered workflow. Deep Agents requires an explicit tools.enabled allowlist (including []) or execute in tools.blocked when local_shell is selected. Cline’s model_schema rejects the openai provider alias; its pinned SDK uses openai-native, and the documented NVIDIA endpoint uses nvidia. Planning does not prove native package availability, authentication, endpoint health, or membership in Pi’s installed model catalog.
If a normalized field has no complete mapping, plan(...) and runtime start
fail with a configuration compatibility error naming the adapter and field.
doctor(...) retains the incompatibility and returns a failed diagnostic check
so callers can inspect all preflight findings. NeMo Fabric does not silently
drop the field. runtime.max_turns is optional, so a config that omits it
remains portable across adapters with different native turn-limit support.
Build the complete nested FabricConfig directly, or start with a base
config and use helpers to add capabilities. For example, extend the config from
the first example with skills, MCP, and telemetry:
Configure Skills
SkillConfig holds the skills section. It has the following fields:
SkillDirectory sets exactly one of skill, a folder that holds SKILL.md, or folder, a folder of skills. BundledSkills has enabled (default True), include, and exclude. include and exclude cannot both be set, and enabled=False takes neither list. For both lists, None and [] mean different things.
The following example loads a folder of skills and one more skill, leaves out one bundled skill, and lets the later entry win a name clash:
Relative paths resolve against base_dir. add_skill_path(path) adds to paths, so it raises ValueError when directories is set; add a SkillDirectory entry instead. remove_skill_path(path) removes the skills section only when nothing else in it is set.
directories, bundled, and duplicates need an adapter whose descriptor advertises them. Planning rejects them otherwise. Refer to Configure Skills for start checks, the output.skills run report, and harness differences.
Set Environment Values Or Forward Them By Name
Use environment.env to set literal values. Use environment.env_names to forward variables that are already available to the NeMo Fabric process.
For example, set GITHUB_TOKEN in the shell that launches your application:
Then extend the configuration with a literal log level and the token’s name:
NeMo Fabric looks up GITHUB_TOKEN in its own process environment and passes the actual value, example-token, to the adapter in RuntimeContext.environment.env. The adapter receives the value, not a name that it must look up. The configuration and run plan contain only the name; NeMo Fabric redacts environment values in the saved adapter invocation. Execution fails if a listed variable is unset. A name cannot appear in both env and env_names.
environment.env does not expand $GITHUB_TOKEN or ${GITHUB_TOKEN}. For example, env={"GITHUB_TOKEN": "$GITHUB_TOKEN"} passes the literal text $GITHUB_TOKEN. Use env_names=["GITHUB_TOKEN"] to request lookup. If your application instead reads the token and places its value in env, that value becomes part of the saved configuration and run plan.
A .env file stores names and values, such as GITHUB_TOKEN=example-token. Neither env nor env_names loads that file. Your launcher or application must load it into the process environment before NeMo Fabric starts the adapter. The same forwarding mechanism works with variables supplied by a shell, CI secrets, or a container.
With Harbor, the NeMo Fabric process runs inside the task environment. env_names reads that process’s variables; listing a name does not copy its value from the Harbor host into the task. Harbor owns delivery through its managed execution environment. The existing Harbor bridge uses a separate environment_env_names payload field and resolves those names into environment.env inside the task runner. That bridge behavior is unchanged by env_names. Refer to Harbor Environment Forwarding for the two-stage flow.
NeMo Fabric reads named values at adapter start and checks them before each invocation. Persistent harnesses and shell backends can retain their startup environment, so NeMo Fabric rejects an invocation if a named value has changed instead of sending a context that disagrees with that environment. The error identifies the variable without exposing its value. Restart the runtime and any associated service after changing a forwarded value. Connecting a new runtime to a service also fails if the named values differ from the service’s startup values.
Configure MCP Authentication And Headers
MCP authentication and custom-header support vary by adapter:
An adapter returns a configuration error when authentication uses a type it
does not support.
Configure OAuth 2.0 with McpAuthenticationConfig. The adapter and MCP server
complete the authorization flow before the first agent turn. The flow can
require interactive browser authorization.
Configure OAuth 2.0 client credentials with type="service_account" when the
agent calls an MCP server as its own service identity, with no user and no
browser. client_secret_env names the environment variable that holds the
client secret; the configuration contains only the name. Use a separate Deep Agents configuration, which supports this authentication type. Install the Deep Agents runtime and adapter, set NVIDIA_API_KEY and JIRA_MCP_CLIENT_SECRET in the launching environment, and replace the example MCP/token URLs and client ID with your service’s values:
The adapter requests a token from token_url, sends it as
Authorization: Bearer <token> with every MCP request, and requests a new one
before it expires. token_endpoint_auth_method selects client_secret_basic
(the default) or client_secret_post, and token_cache_buffer_seconds (300 by
default) sets how early the token is renewed. service_account applies to
sse and streamable-http servers. Startup fails if the variable named by
client_secret_env is unset, if token_url or the server url is not https
(plain http is accepted only for a loopback host), if the transport is
websocket, or if the same server sets an Authorization custom header.
Some MCP servers sit behind a gateway and need two tokens: the
service_account bearer token admits the agent to the server, and a second
token, sent in its own header, selects the identity used for the system behind
the server. That second token can belong to a service account in that system or
to a user, so the agent sees what that account can see. Combine
service_account with a custom_headers entry that references an environment
variable. Create a gateway-only variant of the Deep Agents configuration so it does not inherit the preceding Jira server. Set GATEWAY_CLIENT_SECRET and your downstream token before starting this variant:
Only the service_account token is requested and renewed by the adapter. The
second token is sent as configured, so replace the variable and restart the
runtime when it expires. Set the variable before starting the runtime: an
empty value fails startup with AdapterConfigError, and an unset variable is
not expanded, so the literal ${DOWNSTREAM_TOKEN} text is sent. A rejected
second token does not stop the server’s tools from loading: the gateway
accepts the bearer token, and the error appears in the tool result when the
downstream system refuses the call.
Use custom_headers to send HTTP headers with an sse or streamable-http
server. Header names and values must be valid HTTP header text. To provide a
sensitive value, set it in the process environment and use a ${NAME}
reference in the header value:
Set referenced environment variables before calling run(...) or
start_runtime(...). Do not use McpServerConfig.env for HTTP header
variables; env applies only to stdio MCP server processes.
The Claude adapter stages its MCP configuration in a file for the Claude SDK.
A sensitive value in custom_headers can therefore be written to
disk. Store sensitive values in environment variables and use ${NAME} in
custom_headers. The adapter stages the reference and supplies the value
through the scoped child-process environment instead of writing the value to
the MCP configuration file.
MCP tool policy is scoped to one server and uses the tool names that server
advertises. allowed_tools=None exposes every discovered tool, while an empty
allowlist exposes none. blocked_tools is then removed from the allowed or
discovered set, and the same tool cannot appear in both lists:
An adapter must declare both mcp and mcp.tool_filters support before
planning accepts these fields. The bundled adapters currently support
unfiltered MCP servers only. Per-server MCP policy is distinct from the root
ToolsConfig, which controls adapter-native tools across the harness.
An MCP server requiring authentication also requires mcp.auth.oauth2 or
mcp.auth.service_account, matching its configured authentication type.
tools.definitions names tools and tool groups that the adapter constructs.
Each definition has a portable kind, an adapter-resolved ref, and settings
validated by the adapter descriptor. Use add_tool_definition(...) only when
the selected adapter accepts tools.definitions and publishes a
tool_definition_schema.
tools.enabled and tools.blocked select across the effective named tool
surface. Configure an allowlist, a blocklist, or both:
tools.enabled=None preserves the harness default. An empty list disables every
executable tool. A tool cannot appear in both lists. The selected adapter must
enforce the complete configured policy or planning fails. Hermes interprets
these adapter-native selectors as Hermes toolset names.
Config helpers edit the typed config before planning or starting a runtime.
They do not modify already-started runtimes. Use block_tools(...),
remove_mcp_server(name), and remove_skill_path(path) to edit a copied config.
Telemetry is enabled by adding entries to telemetry.providers; settings
specific to NeMo Relay live in the top-level relay block.
For evaluation or deployment variations, use ordinary Python functions and copies of the typed config. Supply the complete final config to NeMo Fabric.
NeMo Relay observability is represented directly in the SDK config’s top-level
relay block. Configure ATOF file and stream sinks as follows:
To write OpenTelemetry spans to local files, add file_sinks to the opentelemetry section. File sinks need NeMo Relay 0.10 or later. You can use them instead of endpoints or alongside them. When opentelemetry is enabled, it needs at least one endpoint or file sink.
The following example writes OpenInference spans to files instead of sending them to a collector:
NeMo Fabric handles these files as follows:
- As with ATOF and ATIF files, each runtime writes to its own directory:
<output_directory>/<runtime_id>. If you omitoutput_directory, NeMo Fabric usesartifacts/relay. - If you omit
filename, Relay names each file with a timestamp when it starts. A later invocation can then write to a new file. - File sinks append by default. If you set
filename, that file keeps the spans from earlier invocations. To replace it each time Relay starts, set"mode": "overwrite". RunResult.artifactslists each file as an artifact of kindotlp. Its media type isapplication/x-ndjsonfor the defaultjson_linesformat andapplication/x-protobuffor theprotoformat.
Relay buffers spans and writes them in batches. It writes the final batch when it shuts down, so read the files after the runtime stops. If Relay crashes, or is forcibly stopped because it does not shut down in time, a file can be missing its most recent spans.
RelayAtifConfig.model_name is an optional ATIF-only override. When you omit
it, NeMo Fabric writes the selected default model, or the only configured
model, into the Relay plugin configuration. If config.models is empty, the
resolved configuration uses "unknown", matching the adapter fallback.
Multiple model roles without default fail planning before telemetry
resolution.
The derived label preserves ModelConfig.model exactly, including provider
prefixes such as openai/gpt-5-codex. Adapter-specific wire-model translation
does not change this telemetry label. Set the override explicitly only when the
trajectory must use a different label.
Additional NeMo Relay plugin components can be supplied generically with
RelayComponentConfig when their component package is available in the runtime
environment.
The repository’s code-review example uses this pattern for complete Hermes Agent, Codex, Deep Agents, environment, MCP, and telemetry variants.
If a config contains relative paths, pass a base_dir to plan(...),
doctor(...), run(...), prepare_service(...), attach_service(...), or
start_runtime(...). The base directory anchors skills, workspaces, artifacts,
and other relative paths to the caller’s package or job layout.
Configure Dynamic Relay Plugins
Dynamic Relay plugins are configured separately under relay.plugins.dynamic. Enable telemetry.providers.relay with enable_relay() so NeMo Fabric forwards this configuration to the adapter’s Relay integration. The following example configures a dynamic plugin without static components:
NeMo Fabric preserves the relay.plugins section alongside any configured relay.observability, relay.components, and relay.policy. Relay owns manifest validation, loading, and activation. Use absolute manifest paths accessible inside the agent environment. Plugin activation depends on the selected adapter’s Relay integration and the installed Relay version. For Hermes installation requirements, refer to Use the Hermes Agent Adapter.
Feature Support Across Harness Adapters
The SDK presents one consistent shape across adapters, but adapters differ in their runtime requirements, accepted configuration, and optional capabilities.
Use plan(...) and doctor(...) before relying on optional features:
Use the plan to confirm adapter selection and capability routing. Use the doctor report to catch unresolved adapter descriptors, unsupported normalized capabilities, missing declared requirements, and environment problems before starting a runtime.
Capability routes assign execution ownership; they do not describe network
routing. harness_native means the selected adapter executes the capability
through its harness. fabric_managed means NeMo Fabric executes it outside the
harness-native surface. unsupported means neither side can execute it.
Routes apply to tools, skills, and MCP servers. Scalar fields such as
instructions.system and runtime.max_turns are validated separately against
the adapter descriptor.
Custom Fields And Adapter Settings
Use normalized NeMo Fabric fields for portable behavior: models, system instructions, turn limit, runtime, environment, skills, MCP, telemetry, tools, and artifacts.
Supply request context through RunRequest.context for each invocation. Request
context is not part of FabricConfig.
Use harness.settings only for stable, harness-native behavior declared by the
selected descriptor. Each bundled adapter declares a closed settings schema.
Executable paths, Relay command discovery, state directories, and similar
launch mechanics are runtime implementation details rather than public adapter
settings.
Use the optional workflow block to select a registered target by target_id
and provide its immutable construction settings. The Adapter Target Descriptor
selects the adapter, supplies the target-native entry point, and validates
workflow.settings during planning. Fabric then projects the entry point and
settings into AgentConfig.workflow; consumer configuration does not repeat
adapter-specific entry-point semantics. Validation does not apply schema
defaults.
Use FabricConfig.metadata for human-readable agent identity and caller-owned
annotations. NeMo Fabric preserves these values in the resolved configuration
but does not copy them into RunResult.metadata. Use request_id and
RunRequest.context for per-invocation correlation. RunResult.metadata
contains adapter-specific result details.
To group several invocations into one NeMo Relay session, set
RunRequest.relay_session_root to the same UUID string on each
invocation. Deep Agents and mini-SWE-agent, which own an in-process Relay Agent
scope, use it as the propagated Relay root. A UUID request_id stays the
parent; otherwise the session root is also the parent. ATIF exports one
trajectory per invocation under one session_id. An unusable value falls back
to the per-request root without an error, and the invocation still succeeds. A
context key named session_id does not group traces.
For example, invoke each turn with RunRequest(input=message, relay_session_root=conversation_uuid). Core forwards the typed field as AgentRunRequest.relay_session_root. Context keys do not control Relay grouping. Omitting the field preserves per-request behavior. Use matching runtime and adapter-contract versions when sending this field.
Adapter settings are not portable by default. The exact descriptor selected
during planning owns their JSON Schema. Planning and doctor reject settings
that do not satisfy that schema. A descriptor without settings_schema accepts
an empty settings map and rejects a non-empty map. Validation does not apply
schema defaults or otherwise change the settings preserved in RunPlan.
Validation errors identify the adapter, descriptor source and path, and
offending settings path.