What a Colang 1.0 to 2.0 migration involves
Colang 1.0 is still the default in NeMo Guardrails, so existing configurations keep running until a team opts in to Colang 2.x. Migration is therefore a deliberate project with its own scope and test plan. Teams usually start for one of four reasons: they want rail logic that Colang 2.x supports, their Colang 1.0 files have become hard to maintain, they are moving off Colang 1.0 files they have outgrown, or they plan to replace LLM Guard scanners with rails. Confirm which reason applies before estimating work, because each one changes what gets rewritten.
The nemoguardrails convert tool provides a starting point for translating Colang 1.0 files into Colang 2.x. NVIDIA's migration guide states that converted configurations still need manual review, so the output is a draft to test, not a finished migration. Reviewers should check every converted flow, compare each rail's behavior with the original on the same inputs, and list any constructs the tool did not translate. They should also confirm that config.yml and any Python actions still match the converted files.
For most teams, the question is whether to do this in-house or with a partner. A small configuration with a few flows can often be migrated by an experienced team that has time for testing. Larger configurations that span input, dialog, retrieval, execution and output rails, or that replace LLM Guard scanners, usually need more review time and a regression test set. Whichever route you take, ask for a written scope that names the files, rails and test cases covered, and agree who owns the regression results at handover.
What the work includes
The work follows the sequence below, from inventory through rail-by-rail regression testing. Each engagement ends with a converted configuration in version control, a test suite with expected outcomes, a change log of behavior differences, and runbook notes for your team.
Inventory of config and actions
List every config.yml, each Colang 1.0 file and every Python action, along with the rails each one enables and the models it calls. This shows which flows the convert tool will touch and which custom code depends on Colang 1.0 behavior. Check the inventory against what is deployed, not only what sits in the repository.
Convert tool run on a copy
Run the nemoguardrails convert tool on a copy of the configuration folder and keep the output on a separate branch. Record the tool version and the exact command so the run can be repeated. NVIDIA's migration guide says converted configurations still need manual review, so treat the output as a draft.
Review and rewrite converted flows
Compare each converted flow with its Colang 1.0 behavior and rewrite the ones the tool handles poorly. Check flow ordering, message matching, and how intents and dialog states are expressed in Colang 2.0. Where the intended behavior is unclear, confirm it with the flow owner before rewriting.
Custom actions and rail wiring
Update Python actions and the rail definitions in config.yml to match the 2.0 structure. Confirm each input, dialog, retrieval, execution and output rail is still attached to the intended flow, and that action names and parameters match what the Colang files call. A rail that loads but never fires is the failure to test for.
Regression test sets for every rail
Build test sets for input, dialog, retrieval, execution and output rails, each with inputs and expected outcomes taken from the Colang 1.0 system. Include blocked, allowed and borderline cases, plus multi-turn dialogs for flows that depend on conversation state. Run the same sets against both versions and log every difference.
LLM Guard scanner migration
Where LLM Guard input or output scanners duplicate a rail, map each scanner to a NeMo rail or keep it in front of the application. LLM Guard was archived in July 2026, so confirm which scanners you depend on and who will maintain them. Test each replacement against the same inputs before removing a scanner.
What drives effort and duration
This table lists the factors that change how much work a Colang 1.0 to 2.0 migration takes, why each one matters, and how to reduce its effect before work starts.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Colang 1.0 flows and dialog patterns | Each flow the convert tool does not translate cleanly needs hand rewriting and retesting, and the migration guide says converted output still needs manual review. | Inventory flows, group them by pattern, and retire unused flows before converting. |
| Python actions and custom tools | The Colang conversion covers Colang files, so action code usually needs its own review and tests. | List every action and tool early, confirm what the convert tool changes, and review actions separately. |
| Number of rail types enabled | Each enabled rail (input, dialog, retrieval, execution or output) adds flows to design, test and monitor. | Enable only the rails the risk assessment requires and add the rest in stages. |
| Quality of existing test coverage | Without tests of current behavior, teams cannot show that converted rails block and allow the same requests. | Record representative prompts and expected outcomes from the 1.0 system before conversion starts. |
| Model and safety-model calls in the path | Self-check, moderation, fact-checking and content safety models add calls that change latency, cost and failure handling. | Map which rails call which models, and remove rails that duplicate each other. |
| Configurations or languages | Each configuration and language variant multiplies conversion, review and test cases. | Convert one configuration end to end first, then reuse the proven pattern for the others. |
| Python runtime constraints | NeMo Guardrails supports Python 3.10, 3.11, 3.12 and 3.13, which limits base images and dependency versions. | Confirm the target interpreter and pin dependencies before conversion so tests run on the production version. |
| LLM Guard scanners replaced or run alongside | LLM Guard was archived in July 2026 and is no longer maintained, so keeping its scanners adds unmaintained code to the request path. | Map each scanner to a rail or a documented replacement, and decide whether both run during a transition. |
| Approval reviews required by compliance | Each sign-off stage, such as design, test evidence or change approval, adds waiting time that the technical work does not control. | Agree the review list and evidence format in the written scope so reviewers see the same artifacts each time. |
Project phases and outputs
The sequence moves from a recorded inventory and pinned environment to a tested Colang 2.0 configuration that your team can run and upgrade without outside help.
Inventory the current setup and pin the target
DeployOpen and your team list every Colang 1.0 file, config.yml setting, Python action and model provider in use, and record the NeMo Guardrails release and Python version now running. We then choose the target 2.x release, confirm it supports your Python version (the library supports 3.10 to 3.13), and pin it in a lockfile. Done when the inventory and pinned environment are recorded in a document the whole team can review.
Run the conversion tool on a copy
Run the nemoguardrails convert tool against a copy of the Colang 1.0 folder, never the production source. Keep the original and the converted output in version control so every change is traceable. NVIDIA's migration guide says converted configurations still need manual review, so expect gaps. Done when each file has a converted counterpart and the conversion warnings and errors are logged.
Review and rewrite converted flows
An engineer familiar with Colang 2.0 reads each converted flow against its original intent, fixes constructs the tool did not translate, and rewrites flows that depend on Colang 1.0 behavior. Your business owners confirm refusal and handoff wording. The output is a reviewed Colang 2.0 configuration and a change log linking each rewritten flow to its original and to the reason for the change.
Map LLM Guard scanners to rails
If the current application uses LLM Guard scanners, we list each one and decide whether a NeMo Guardrails rail, a built-in moderation or injection check, or a custom action covers the same risk. LLM Guard was archived in July 2026 and is no longer maintained, so the replacement also needs a named owner. If LLM Guard is not in use, this step closes with a written statement saying so.
Compare behavior with regression tests
Build a test set from recorded prompts, expected refusals, allowed topics and known jailbreak attempts, then run it against the old and new configurations side by side. Each difference is classified as an intended fix, a regression or an open question. The output is a comparison report showing each prompt, both responses and the disposition, with every regression fixed or accepted in writing before cutover.
Cut over in stages with rollback
Move traffic to the Colang 2.0 configuration in stages, starting with a limited share of requests or a non-critical application, and watch blocked-request logs and error rates at each stage. Keep the Colang 1.0 deployment available until the cutover is accepted. The output is a cutover record with tested rollback steps, the conditions that trigger a rollback and a sign-off for each stage.
Hand over runbooks and ownership
Transfer the Colang 2.0 configuration, Python actions, test suite, pinned dependencies and migration notes to your repository, and walk your engineers through running the regression suite before any future upgrade. Named owners take over the configuration and the test set. The output is a handover package with runbooks, an ownership list and a passing regression run in your environment.
What stays in-house and what goes to a partner
This table shows, for each part of a Colang 1.0 to 2.x migration, whether the client team usually keeps it, a partner usually takes it, and which skills the work requires.
| Work part | Usually kept in-house | Usually outsourced | Skills needed |
|---|---|---|---|
| Owning business policy for each rail | Yes. Product and risk owners define what each rail must block, allow, or escalate, and sign off on wording. | Not applicable. A partner may document policy as it is decided but should not set it. | Product management, risk and compliance knowledge, domain expertise |
| Reviewing rail behavior with product owners | Yes. Owners test sample conversations and confirm the bot still behaves as intended. | Partner prepares test conversations, logs and a summary of differences for the review. | Conversation design, product judgment, clear written communication |
| Writing Colang 2.x flows | Shared. Keep at least one engineer able to read and change the flows after handover. | Partner rewrites converted flows, removes conversion artifacts and documents the result. | Colang 2.x syntax, event-driven dialog design, Python |
| Python action changes | Shared. Owners of the calling application review any change to action signatures or return values. | Partner updates action code for the new flow model and adds unit tests. | Python, the NeMo Guardrails action API, API integration patterns |
| Building regression suites | Owners approve the expected outcomes for each prompt in the suite. | Partner builds the suite from current Colang 1.0 behavior and extends it to 2.x paths. | Test design, Python test tooling, LLM output evaluation |
| Mapping LLM Guard scanner rules | Yes. Security owners decide which scanner outcomes must block, flag or pass. | Partner maps each scanner rule to an equivalent rail or a documented replacement. | Security engineering, input and output filtering, knowledge of the archived LLM Guard project |
| Setting up runtime and secrets | Yes. Platform team owns the environment, model credentials and secret storage. | Partner configures the server or library runtime, the configuration folder and secret injection. | Container and Kubernetes operations, secrets management, Python packaging |
| Cutover support | Yes. The on-call owner decides when to switch traffic and when to roll back. | Partner supports the switch, monitors blocked requests and fixes issues found in the first days. | Release management, observability, incident response |
What usually goes wrong
Most failures in this migration come from accepting converted output without checking behavior, not from the conversion itself. Each risk below has a specific check to run before cutover.
Converted output accepted unreviewed
The nemoguardrails convert tool gives you a starting point, and NVIDIA's migration guide says converted configurations still need manual review. Diff each converted file against its 1.0 original, read every flow, and log each manual change so the team can see what was altered and why before sign-off.
Flow changes that pass validation
A Colang 2.x configuration can load without errors while matching different user messages or triggering rails in a different order than the 1.0 original. Build a before-and-after table of sample inputs with the expected rail decision for each, then run it against both versions and review every mismatch.
Rarely triggered rails left untested
Rails that fire on uncommon inputs, such as edge-case jailbreak phrasing or off-topic requests, often have no test coverage. A broken conversion can then stay hidden until production traffic reaches them. List every rail in the configuration and write at least one test for each, including the ones that seldom fire.
Python actions tied to old flow
Custom actions may depend on variables, event order or return values produced by the 1.0 flow. After conversion, check each action's inputs and outputs against the new flow and confirm it still runs at the intended points. Test actions in isolation so a failure traces back to the action itself.
LLM Guard rules that do not map
LLM Guard was archived in July 2026 and is no longer maintained, so its scanners will not receive fixes. Its rules do not map one-to-one to NeMo Guardrails rails, so each scanner needs a documented equivalent, an accepted gap, or a decision to drop it. Compare detection results on the same test set before retiring the old scanner.
Mixed Colang versions in one configuration
During a staged move, a configuration folder can end up with Colang 1.0 and 2.x files side by side, and 1.0 is still the default. Set the Colang version explicitly in config.yml, confirm the setting works in the NeMo Guardrails release you deploy, and block changes that add files in the other version.
How the work differs by starting point
Illustrative: a configuration with a handful of Colang 1.0 flows, a few rails and no custom actions. The convert tool usually handles most of this, so the work is mainly review and regression testing.
- Run the convert tool on a copy kept in version control and diff every output file against the original.
- Review each converted flow by hand, because NVIDIA's migration guide says converted configurations still need manual review.
- Test each rail type you use with a fixed set of prompts before and after conversion.
- Confirm that your Python version is 3.10, 3.11, 3.12 or 3.13, and pin the library version you tested.
- Confirm whether the configuration is called through the Python API or loaded by a server, since that changes the test harness.
Illustrative: several teams share Python actions and imported Colang files across separate application configurations. Conversion touches shared code, so one change can break other teams' rails.
- Inventory which flows and actions are imported by more than one configuration before converting anything.
- Agree a change window and a named owner for each shared module.
- Build a regression suite per configuration and have each team run it before shared files move to 2.x syntax.
- Confirm whether teams need different library versions during the transition and how each version will be pinned.
- Ask who signs off on converted shared files and who owns the test results.
LLM Guard was archived in July 2026 and is no longer maintained, so this work replaces scanner coverage as well as syntax. Map each scanner you use to a rail you configure in NeMo Guardrails, or to a control you keep outside the framework.
- List every LLM Guard input and output scanner in use and where each one runs in the request path.
- Map each scanner to an input, dialog, retrieval, execution or output rail, or to a control you keep elsewhere.
- Confirm the model and inference cost of any NeMo Guardrails safety model that replaces a scanner, using the vendor documentation.
- Run LLM Guard in parallel and compare blocked and allowed outputs on the same test set before cutover.
- Confirm where scanner findings were logged and whether the new logs feed the same review process.
Where the framework runs changes how you test and operate it. Inside an application, the Python API runs with your code. As a guardrails server or in Kubernetes, configurations load from a folder and are exposed over HTTP, so each configuration change also changes the API.
- Library: test through the same Python calls your application makes, and check whether the LangChain integration is enabled through its environment variable.
- Server: run the provided Dockerfile or your own image with the converted configuration folder, then test the HTTP endpoints.
- Kubernetes: confirm whether you will use NVIDIA's microservice deployed with Helm or build your own image.
- Confirm how configuration folders are versioned, promoted and rolled back in each environment.
Packages, model files and safety-model downloads must be mirrored before the work starts. A conversion or test run that reaches for an external dependency will fail or, worse, behave differently without warning.
- Mirror the nemoguardrails package from PyPI and its dependencies for each Python version in use.
- Confirm which built-in detection and safety models need local copies and that they are present on the test network.
- Pin the release you tested, for example v0.24.1 if that is your target, and record its checksum in your change record.
- Check that no rail calls an external model or API at runtime, and fail tests if outbound connections occur.
- Confirm who approves artifacts crossing the boundary and how long that approval takes in your organization.
What you need to provide
Before the migration starts, your team needs to hand over a complete source set: the repository containing config.yml, every Colang 1.0 file, and the Python actions those flows call. Converted flows are only as accurate as the files the convert tool reads, so a partial export, or actions kept in a separate team's repository, will produce a migration that looks complete and quietly drops behavior. Confirm that the repository includes any shared Colang imports and the exact NeMo Guardrails version the current rails were tested against.
Provide sample conversations or traffic logs that show the behavior you expect from each rail, including refusals, topic redirects and retrieval-grounded answers. Without them, the review of converted flows has no reference point, and a reviewer can only check syntax. Include examples that should be blocked and examples that must pass, since the Colang 2.x flow semantics can change which utterances match a flow. Logs should be scrubbed of personal data before they leave your environment.
Grant access to a non-production environment that calls the same model endpoints, safety models and LLM providers as production, or approved stand-ins with comparable behavior. Rail outcomes depend on the model that judges them, so a migration validated against a different model proves little. Also decide on the target NeMo Guardrails version and Python version from the versions the project supports (3.10 through 3.13 at the time of writing, per the README). Confirm both with your platform team before work begins.
Name one owner per rail who can approve the intended policy, and set an approval path for any behavior change the migration reveals. Expect differences that a convert tool cannot resolve, such as a flow that now matches more broadly. Those differences need a business decision, not an engineering guess. Finally, provide access to the safety-model and LLM provider accounts the rails call, so the team can run tests, and confirm who pays for that test traffic.
Frequently asked questions
Is the nemoguardrails convert tool enough to migrate Colang 1.0 to 2.0?
No. The convert tool gives you a starting point, and NVIDIA's migration guide says converted configurations still need manual review. Check each converted flow against the original intent, confirm that config.yml settings and Python actions still load, and run your test conversations before anything reaches production. Treat the tool output as a draft that a developer reviews line by line.
How much effort does a Colang 2.0 migration take?
Effort depends mainly on how many flows, rails and custom actions your configuration contains and how much of its behavior your tests cover. A small configuration with broad regression tests is a short review. A large configuration with few tests means reviewing every converted flow by hand and building the missing tests first. Build an inventory of files, flows, actions, rails and test cases so you can estimate from your own numbers, and ask any partner to quote from that inventory.
Can our own team migrate NeMo Guardrails to Colang 2.0 without outside help?
Yes, if your team knows Python, Colang 2.0 concepts and the behavior your guardrails are meant to enforce. The work is mostly careful review and testing, so the deciding factors are that Colang familiarity, ownership of the test suite and the time available for detailed review. Teams with little Colang experience or few tests often find the review harder than the conversion itself. An outside partner can take on review and test-building under a written scope while your team keeps ownership of policy decisions.
What do we need to provide for a guardrails migration?
Plan to provide access to the current configuration repository, the Python actions, and the environment where guardrails run, whether that is the Python library or a server. You also need test conversations or logs of blocked and allowed requests, plus a named person who can decide the intended behavior for each rail. Access to the LLM and safety-model endpoints used during testing matters too, because rails call models at runtime.
How does LLM Guard retirement affect our migration plan?
LLM Guard was archived in July 2026 and is no longer maintained, so every scanner you currently run through it needs a replacement decision and a test plan. List each scanner, decide whether NeMo Guardrails' built-in rails or another maintained tool covers the same need, and test the replacement against the same inputs. Keep this work separate from the Colang conversion so that a change in detection behavior is not mistaken for a conversion defect.
Will the behavior be identical after converting to Colang 2.0?
Do not assume it will be. Colang 2.0 uses different syntax, and NVIDIA's guide says converted configurations need manual review. Confirm equivalence by running the same set of conversations against the old and new configurations and comparing which messages are blocked, which responses are returned and how fallbacks behave. Record each accepted difference with its reason so the team can sign it off before cutover.
How DeployOpen delivers this service
DeployOpen plans and carries out Colang 1.0 to 2.x migrations for NeMo Guardrails inside your own infrastructure, with each rail's behavior checked after conversion rather than trusted from the converter output alone. Engagements are fixed-scope, with the work agreed in writing before it starts.
How we scope
- We inventory every Colang 1.0 file, config.yml setting, and Python action that the migration must carry across.
- We agree in writing which rail types, flows and models the migrated configuration must cover before any conversion runs.
- We record which Colang 1.0 behaviors need manual rewrite, and state in the scope what ongoing support is available as a retainer.
How we build
- We run the nemoguardrails convert tool on a copy of your configuration, then review its output file by file against the original.
- We rewrite constructs the converter misses or converts incorrectly, and test each input, dialog and output rail against recorded example conversations.
- We pin the NeMo Guardrails version used for testing so the migrated configuration is validated against the release you will run.
How we hand over
- You receive the migrated Colang 2.x configuration with a change log mapping each original Colang 1.0 flow to its replacement.
- You receive a regression test set covering blocked and allowed cases, plus notes on behavior that changed between the two Colang versions.
- Your engineers walk through the runbook for deploying the configuration as a Python library or as a guardrails server you operate.
How we support
- After handover we can rerun the regression tests against new NeMo Guardrails releases, including any release that changes Colang behavior.
- If you are moving from LLM Guard, we can map its input and output scanners to equivalent NeMo Guardrails rails and confirm which gaps remain.
- Ongoing support, upgrades and continuous testing are available as retainers, and the terms are agreed in writing before work starts.
