NeMo Fabric adapter
How to write a NeMo Fabric adapter for your own agent
A NeMo Fabric adapter is two things: a descriptor file that tells Fabric what the adapter is called and what it accepts, and a runtime class with three operations, start, invoke and stop. Fabric hands the adapter the model, the instructions and the limits in a common form, and the adapter turns those into your agent. NVIDIA's smallest example is about 350 lines for the required parts. Katonic wrote one for its own agent definitions in November 2026, and this page is the method we used.
The parts of an adapter
| Part | What it does | Required |
|---|---|---|
| Descriptor | A JSON file with the adapter ID, the module to run, the settings it takes, the configuration fields it accepts, telemetry outputs and capabilities | Yes |
| Runtime class | start builds the agent, invoke runs one turn, stop cleans up | Yes |
| Configuration translation | Turns Fabric's model, instructions and limits into your model client and prompt | Yes |
| Streaming | Sends chat completion chunks as tokens arrive | Optional |
| Relay telemetry | Reports model and tool calls through NeMo Relay | Optional |
| Tool servers | Connects tools the caller supplies | Optional |
Step by step
- Start from NVIDIA's custom LangGraph example in the NeMo Fabric repository. It ran first time for us in every mode.
- Write the descriptor. Pick an adapter ID in your own namespace, name the runner module, and list the settings your adapter needs, such as a path to an agent definition.
- Write the runtime class. In start, read the settings and build the agent once. In invoke, run one turn and return the status, the output and token usage. Keep message history on the runtime if you want sessions.
- Take the model from Fabric. Read the model name, the base address and the name of the environment variable that holds the key from Fabric's configuration. Read the key from that variable when you build the model client, and never store or print it.
- Hand the class to Fabric's serve function. It runs the lifecycle protocol for you.
- Point Fabric at your descriptor through its discovery settings while you develop, then package the descriptor so an install places it where Fabric looks.
Adding streaming
- Set the streaming capability to true in the descriptor and add one method that receives an emit function.
- Emit chunks in the OpenAI chat completions chunk format as your model streams.
- Declare the capability only if the method exists. A descriptor that claims streaming without the method leaves the runtime in a failed state when a caller uses it.
- A caller that stops reading does not cancel the run, and one runtime handles one invocation at a time. A chat service needs one runtime per live conversation.
Pitfalls we hit
- Fabric starts the adapter under the system Python unless a virtual environment is active. Set the ADAPTER_PYTHON variable to your environment's Python, or activate the environment. We reported this as NeMo Fabric issue 635.
- Leave the turn limit unset for a tool-calling agent. A limit of one stops the agent before it can answer.
- An editable install does not place the descriptor where Fabric discovers it. Use the discovery settings during development.
- The adapter contract was at an alpha version in November 2026. Expect to update the adapter when it changes.
- Decide what to do with configuration your adapter cannot honour. Ours refuses to start by default, so nothing is silently dropped.
Testing
- Unit tests with a scripted model, so they run without a network or a key. Ours has 39.
- Then four live checks through Fabric: plan, a run that calls a tool, a two-message session where the second answer depends on the first, and a streamed run where the chunks match the final response.
- Fabric publishes conformance guidance for adapters. Run it before you offer the adapter to others.
Contributing an adapter
Pull requests on NeMo Fabric are limited to approved developers. Outside contributors open an issue with a design or a patch description, and a maintainer can adopt it. Katonic proposed its adapter that way, with a fallback of publishing it separately and asking for a list of community adapters in the documentation.
The Katonic adapter
Every agent built in Katonic is a declarative definition that compiles to NVIDIA's open agent software. The Katonic adapter reads such a definition and runs it through NeMo Fabric as a tool-calling agent, with streaming and optional NeMo Relay telemetry. It is about 1,100 lines with a 77-line descriptor. It covers the model, the system prompt, tools and turn limits today, and refuses definitions that use knowledge sources, guardrail profiles or approval gates until those are added.
Read next
- What is NVIDIA NeMo Fabric? →
- NVIDIA NeMo Helix, Relay and Fabric: field guide →
- How to use NeMo Relay with LangGraph →
- Issue 636: Katonic adapter proposal →
- Issue 635: adapter starts under system Python →
- Issue 634: Remote Agent streaming capability →
- NeMo Fabric on GitHub →
Questions and answers
How do I write a NeMo Fabric adapter?
Write a descriptor file and a runtime class with start, invoke and stop operations, and hand the class to Fabric's serve function. Start from NVIDIA's custom LangGraph example.
How big is a NeMo Fabric adapter?
The required parts of NVIDIA's smallest example are about 350 lines. Katonic's adapter, with streaming and telemetry, is about 1,100 lines.
Can a NeMo Fabric adapter stream tokens?
Yes. Declare the streaming capability in the descriptor and add a method that emits chat completion chunks.
Why does my adapter fail with "No module named nemo_fabric_adapters"?
Fabric started it under the system Python. Set ADAPTER_PYTHON to your environment's Python or activate the environment.
Can I contribute an adapter to NeMo Fabric?
Yes, through an issue. Pull requests are limited to approved developers, and a maintainer can adopt an outside contribution.
Which version is this based on?
NeMo Fabric 0.6.1 and the adapter contract version in use in November 2026, which was still alpha.