> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server. # Colang Guide > Learn Colang, the event-driven language for defining guardrails flows and bot behavior. Colang is an *event-driven interaction modeling language* that is interpreted by a Python runtime. This section describes how to use Colang to define guardrails flows in `.co` files. The initial releases of the NeMo Guardrails library (versions 0.1 through 0.7) use Colang 1.0. Beginning with version 0.8, the NeMo Guardrails library introduces support for Colang 2.0, while maintaining Colang 1.0 as the default until Colang completes its beta phase. | NeMo Guardrails Library Version | Colang Version | | ------------------------------- | -------------- | | 0.1 - 0.7 | 1.0 | | 0.8 | 2.0-alpha | | >= 0.9 | 2.0-beta | ## Motivation Large Language Models (LLMs) are increasingly used in different types of conversational and interactive systems, such as chat-based assistants, voice assistants, multi-modal interactive avatars, non-playable characters in games, and fully autonomous agents. These applications use the LLMs to do more than generate text responses. They need to trigger actions and follow complex business processes. ![Use cases for LLMs in interactive systems](file:_dot_dot_/_dot_dot_/_dot_dot_/_dot_dot_/_dot_dot_/private/var/folders/gv/z1x0xgb54bj3k7vlncdh6pnc0000gp/T/tmp-30368-jW1namjpUIjU/docs/configure-rails/colang/colang-2/images/use_cases_llms.png "Use cases for LLMs in interactive systems") Widely adopted approaches for achieving this include: 1. Generating code and executing it in a sand-boxed environment (for example, generate Python code). 2. Generating the response using specific templates, which allow easier parsing of bot responses and actions that should be taken (for example, Chain of Thought patterns). 3. Function calling and constrained output generation (for example, JSON mode) for models that support it. Retrieval Augmented Generation (RAG) plays a crucial role by integrating application-level and user-specific context into the generation. A comprehensive guardrails library for LLMs should seamlessly accommodate all these interaction patterns. ## Configuration Sections The following sections provide detailed documentation for using Colang: #### [Colang 2.0 Guide](/configure-guardrails/colang/colang-2) Reference and tutorials for Colang 2.0 syntax, runtime behavior, and standard library flows. Beta #### [What's Changed in Colang 2.0](/configure-guardrails/colang/colang-2/whats-changed) Review the major language and runtime changes from Colang 1.0 to Colang 2.0. #### [Colang 2.0 Migration Guide](/configure-guardrails/colang/colang-2/migration-guide) Convert Colang 1.0 configurations to Colang 2.x and learn the migration path. Guide #### [Colang 1.0 Guide](/configure-guardrails/colang/colang-1) Reference and tutorials for Colang 1.0 syntax for defining dialog flows and guardrails. #### [Colang Usage Examples](/configure-guardrails/colang/usage-examples) Learn common Colang patterns for bot message instructions and extracting user-provided values. ## Colang 1.0 When referring to Colang, both the language and its runtime environment are implied. The initial Colang 1.0 language and runtime have several limitations. **Language limitations:** * Primarily supports text-based interactions with specialized constructs for user and bot messages, rather than multi-modal interactions (e.g. using voice, gestures, posture, or images). * Limited support for natural language instructions, such as extracting user-provided values or bot message instructions. * Lack of support for executing multiple actions or initiating multiple interaction flows concurrently. * Does not allow the modeling of parallel interaction streams, such as simultaneous chat and avatar posture adjustments in interactive avatar systems. * Absence of a formal language description. **Runtime limitations:** * No explicit state object to manage continuous interaction. * Performance degrades as the number of events increases. ## Colang 2.0 Colang 2.0 represents a complete overhaul of both the language and runtime. ### Colang 2.0-alpha Key enhancements include: * A more powerful flows engine supporting multiple parallel flows and advanced pattern matching over the stream of events. * A standard library to simplify bot development. * Smaller set of core abstractions: flows, events, and actions. * Explicit entry point through the `main` flow and explicit activation of flows. * Asynchronous actions execution. * Adoption of terminology and syntax akin to Python to reduce the learning curve for new developers. ### Colang 2.0-beta Additional enhancements: * An import mechanism for the standard library to further streamline development. * The new *generation operator* (`...`). * Standalone and flow parameter expression evaluation. **Current limitations** (to be fixed in future releases): * Guardrails Library is not yet fully usable from within Colang 2.0. * Some generation options not supported (for example, log activated rails). ### Migration from Alpha to Beta You can migrate your Colang 2.0-alpha bots to 2.0-beta using the following command: ```bash nemoguardrails convert "path/to/2.0-alpha/version/bots" --from-version "2.0-alpha" ``` Additionally, you can add the `--validate` flag to check if the migrated files raise any Colang syntax errors. ## Interaction Model While there are many changes in the syntax and the underlying mechanics between Colang 1.0 and Colang 2.0, one core element has remained the same: *interaction model*. In both Colang 1.0 and Colang 2.0, the interaction between the application (or user) and the LLM is an event-driven one. Examples of events include: user saying something, the LLM generating a response, triggering an action, the result of an action, the retrieval of additional info, and the triggering of a guardrail. In other words, the evolution of a system is modeled as a series of events, with the guardrails layer responsible for recognizing and enforcing patterns within the stream. The diagram below depicts a simplified version of the role of the events stream (the boxes with yellow background represent events). ![Event-driven interaction model showing the flow of events between user, guardrails, and LLM](file:_dot_dot_/_dot_dot_/_dot_dot_/_dot_dot_/_dot_dot_/private/var/folders/gv/z1x0xgb54bj3k7vlncdh6pnc0000gp/T/tmp-30368-jW1namjpUIjU/docs/configure-rails/colang/colang-2/images/guardrails_events_stream.png "Event-driven interaction model showing the flow of events between user, guardrails, and LLM") This event-driven interaction model is part of what makes Colang a powerful modeling language, enabling the description of any type of interaction (text-based, voice-based, multi-modal, agent, multi-agent, etc) and adding guardrails to it. ## Getting Started If you've used Colang 1.0 before, check out the [What's Changed with Colang 2.0](/configure-guardrails/colang/colang-2/whats-changed) page. If not, you can get started with the Colang 2.0 [Hello World](/configure-guardrails/colang/colang-2/getting-started/hello-world) example. > Learn Colang, the event-driven language for defining guardrails flows and bot behavior. ## Docs - [Colang 2.0 Guide](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2.md): Learn Colang 2.0 syntax, concepts, migration guidance, tutorials, and language reference topics. - [What's Changed](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/whats-changed.md): This guide provides a non-comprehensive overview of the most important changes in Colang 2.0. - [Migrating from Colang 1 to Colang 2](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/migration-guide.md): Convert Colang 1.0 configurations to Colang 2.x using the nemoguardrails convert tool. - [Getting Started with Colang 2.0](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started.md): Build Colang 2.0 guardrails step by step, from Hello World to LLM and multimodal flows. - [Hello World](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/hello-world.md): This section introduces a "Hello World" Colang example. - [Interaction Loop](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/interaction-loop.md): This section explains how to create an interaction loop in Colang 2.0. - [Input Rails](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/input-rails.md): This section explains how to create *input rails* in Colang 2.0. - [Dialog Rails](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/dialog-rails.md): This section explains how to create dialog rails using Colang. - [LLM Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/llm-flows.md): This section explains how to create LLM-driven flows in Colang 2.0. - [Multimodal Rails](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/multimodal-rails.md): This section explains how to create multimodal rails in Colang 2.0. - [Recommended Next Steps](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/getting-started/recommended-next-steps.md): The Colang 2.0 getting started guide introduces you to a basic Hello World example, and then goes into Dialog Rails, Input Rails, Multimodal Rails, and other Colang 2.0 concepts l - [Colang 2.0 Language Reference](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference.md): Reference documentation for Colang 2.0 syntax, events, actions, flows, variables, and the standard library. - [Introduction](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/introduction.md): Colang is an event-based modeling language to enable the design of highly flexible conversational interactions between a human and a bot. Since learning a new language is not an ea - [Event Generation & Matching](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/event-generation-and-matching.md): When working with Colang, we assume to have a common event channel that contains all relevant events happening in the interactive system. From a Colang perspective, relevant events - [Working with Actions](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/working-with-actions.md): You have seen in section Event Generation & Matching how to work with events. We will now introduce actions that will enable you to better manage events and their temporal dependen - [Defining Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/defining-flows.md): So far you have seen only one flow, the main flow. But in Colang we can define many different flows, like functions in other programming languages. A flow defines a specific intera - [Working with Variables & Expressions](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/working-with-variables-and-expressions.md): Like Python, Colang supports these fundamental data types: `string`, `int`, `float`, `bool`, `list`, `set`, `dict`, in addition to the Colang specific event, action and flow refere - [Flow control](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/flow-control.md): Flow control is an essential tool in all programming languages, and Colang supports this as well. It enables branching and repetition of interaction patterns in a single flow. - [Colang Standard Library (CSL)](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library.md): The Colang Standard Library (CSL) provides an abstraction from the underlying event and action layer and offers a semantic interface to design interaction patterns between the bot - [Fundamental Core Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library/core.md): The core library that contains all relevant flows related to user and bot utterance events and actions. - [Timing Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library/timing.md): Flows related to timing and reacting to periods of silence. - [LLM Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library/lmm.md): Trigger a bot utterance similar to given text - [Interactive Avatar Modality Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library/avatars.md): **User Event Flows** - [Guardrail Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library/guardrails.md): Flows to guardrail user inputs and LLM responses. - [User Attention Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/the-standard-library/attention.md): Flows to handle user attention. - [Make use of Large Language Models (LLM)](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/make-use-of-llms.md): At its core, Colang does not require a Large Language Model (LLM) as backend. However, many of the more advanced mechanisms in the Colang Standard Library (CSL) depend on one. - [More on Flows](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/more-on-flows.md): In section Defining Flows, we learned the core mechanisms of flows. In this section will look at more advanced topics that are related to flows. - [Python Actions](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/python-actions.md): In the section Working with Actions, you have seen how actions can be used in the context of UMIM events. Additionally, you can also use the action concept to call custom python fu - [Development and Debugging](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-2/language-reference/development-and-debugging.md): Currently, the Colang story designing and building environment is fairly limited, but will be improved on in the future. - [Colang 1.0 Guide](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1.md): Reference and tutorials for Colang 1.0 syntax for defining dialog flows and guardrails. - [Colang 1.0 Language Syntax](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/colang-language-syntax-guide.md): Comprehensive syntax guide for Colang 1.0 including messages, flows, variables, and patterns. - [Colang 1.0 Tutorials](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials.md): Step-by-step tutorials for building guardrails with Colang 1.0 from Hello World to RAG. - [Hello World](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/1-hello-world.md): Create your first guardrails configuration to control greeting behavior with Colang 1.0. - [Core Colang Concepts](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/2-core-colang-concepts.md): Learn essential Colang concepts including messages, flows, context variables, and LLM integration. - [Demo Use Case](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/3-demo-use-case.md): Introduction to the ABC Bot example used throughout the Colang 1.0 tutorial series. - [Input Rails](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/4-input-rails.md): Add input rails to validate and filter user messages before LLM processing. - [Output Rails](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/5-output-rails.md): Add output rails to filter and validate LLM responses before returning to users. - [Topical Rails](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/6-topical-rails.md): Implement topical rails to keep conversations on-topic and prevent off-topic discussions. - [Retrieval-Augmented Generation](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/tutorials/7-rag.md): Apply guardrails to RAG scenarios with knowledge base integration and fact checking. - [Guardrailing Bot Reasoning Content](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/colang-1/bot-thinking-guardrails.md): Inspect and control LLM reasoning traces to block problematic patterns or enhance moderation decisions. - [Colang Usage Examples](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/usage-examples.md): Practical examples of Colang patterns for bot messages, value extraction, and flow control. - [Bot Message Instructions](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/usage-examples/bot-message-instructions.md): Provide custom instructions to control how the LLM generates bot messages in Colang 1.0 and 2.0. - [Extract User-provided Values](https://docs.nvidia.com/nemo/guardrails/v0.24.0/configure-guardrails/colang/usage-examples/extract-user-provided-values.md): Extract and store user-provided values like names, dates, and queries in context variables.