Getting Started with Colang 2.0

This guide will walk you through creating your first Colang 2.0 bot, from a simple “Hello World” to implementing guardrails.

Prerequisites

Install NeMo Guardrails:

pip install nemoguardrails

Ensure you’re using version 0.9 or later for Colang 2.0-beta support.

Hello World

Let’s start with the simplest possible Colang 2.0 script.

Your First Script

Create a file called rails.co:

import core

flow main
  user said "hi"
  bot say "Hello World!"

Key concepts:

Import statement: import core loads the standard library with user said and bot say flows
main flow: The entry point of every Colang 2.0 script
user said: Matches when the user says something specific
bot say: Instructs the bot to respond with a message

Testing

Test your script using the NeMo Guardrails CLI:

nemoguardrails chat --config=.

> hi
Hello World!

> something else is ignored

>

This example doesn’t use the LLM. You must type exactly “hi” to get a response. We’ll add LLM support next.

Adding LLM Support

To make your bot more flexible, integrate LLM support.

LLM-Powered Hello World

Update rails.co:

import core
import llm

flow main
  activate llm continuation
  activate greeting

flow greeting
  user expressed greeting
  bot express greeting

flow user expressed greeting
  user said "hi" or user said "hello"

flow bot express greeting
  bot say "Hello world!"

What changed:

import llm: Adds LLM capabilities
activate llm continuation: Enables the LLM to generate responses
activate greeting: Makes the greeting flow active
Separate intent flows: user expressed greeting and bot express greeting define intents

Configuration

Create config.yml:

colang_version: "2.0"

models:
  - type: main
    engine: openai
    model: gpt-4

Testing with LLM

nemoguardrails chat --config=.

> Hi there!
Hello world!

> Hey
Hello world!

> How are you?
[LLM generates response]

Now the bot recognizes variations of “hi” and “hello” thanks to the LLM.

Understanding Flows

Flow Types

Colang 2.0 has several flow types:

Main flow: The entry point (flow main)
Active flows: Activated and run in background
Regular flows: Called explicitly or by event matching

Flow Syntax

flow <name> [parameters] [-> return values]
  ["""docstring"""]
  # flow body

Example with parameters:

flow bot say $text $intensity=1.0
  """Bot says given text."""
  await UtteranceBotAction(script=$text, intensity=$intensity)

Flow Events

Flows generate events:

Started: When a flow begins
Finished: When a flow completes successfully
Failed: When a flow fails

Match these events:

flow main
  start bot express greeting as $flow_ref
  match $flow_ref.Finished()
  # Continue after greeting finishes

Real Example: Interaction Loop

From examples/v2_x/tutorial/interaction_loop/main.co:

flow main
  match UtteranceUserAction.Finished(final_transcript="Hi")
  start UtteranceBotAction(script="Hi there! How are you?") as $ref_action_1
  match $ref_action_1.Finished()
  match UtteranceUserAction.Finished(final_transcript="Good and you?")
  start UtteranceBotAction(script="Great! Thanks") as $ref_action_2
  start GestureBotAction(gesture="Thumbs up") as $ref_action_3
  match $ref_action_2.Finished() and $ref_action_3.Finished()

Key features:

Action matching: match UtteranceUserAction.Finished()
Flow references: as $ref_action_1 stores a reference
Parallel actions: Both $ref_action_2 and $ref_action_3 start simultaneously
Multi-modal: Combines utterance and gesture

Adding Guardrails

Let’s add input guardrails to check user messages.

Input Rails Example

From examples/v2_x/tutorial/guardrails_1/rails.co:

import core
import guardrails
import llm

flow main
  activate llm continuation
  activate greeting

flow greeting
  user expressed greeting
  bot express greeting

flow user expressed greeting
  user said "hi" or user said "hello"

flow bot express greeting
  bot say "Hello world!"

flow input rails $input_text
  $input_safe = await check user utterance $input_text

  if not $input_safe
    bot say "I'm sorry, I can't respond to that."
    abort

flow check user utterance $input_text -> $input_safe
  $is_safe = ..."Consider the following user utterance: '{$input_text}'. Assign 'True' if appropriate, 'False' if inappropriate."
  print $is_safe
  return $is_safe

Key features:

import guardrails: Loads guardrails support
input rails flow: Special flow called for every user input
Generation operator (...): Uses LLM to evaluate safety
abort: Stops processing if input is unsafe

The Generation Operator

The ... operator invokes the LLM at runtime:

$result = ..."Natural language instruction for the LLM"

In the example above, it asks the LLM to evaluate if the input is safe.

Flow Activation

Flows can be activated to run in the background:

flow main
  activate llm continuation  # Enables LLM-driven responses
  activate greeting          # Watches for greeting events
  activate safety_check      # Monitors for safety issues

Activated flows match their patterns throughout the conversation.

Working with Variables

Variables in Colang 2.0 start with $:

flow example
  $name = "Alice"
  $count = 5
  $result = await some_action()
  
  if $count > 0
    bot say "Count is positive: {$count}"

Global Variables

Use the global keyword for variables shared across flows:

flow main
  global $user_authenticated = False
  activate authentication

flow authentication
  global $user_authenticated
  
  user provided credentials
  $user_authenticated = True

Keywords Reference

Core Keywords

flow: Define a flow
import: Import a module
activate: Activate a flow to run in background
match: Wait for an event
send: Send an event
start: Start a flow/action without waiting
await: Start and wait for completion
return: Return a value from a flow
abort: Stop the current flow
global: Declare a global variable

Control Flow

if/else: Conditional branching
when/or when: Event-based branching
and/or: Logical operators

Operators

...: Generation operator (LLM invocation)
as: Store a reference
->: Define return values

Standard Library Overview

The standard library provides essential flows:

core Module

import core

# Available flows:
# - user said "text"
# - bot say "text"
# - user said something
# - bot said something

llm Module

import llm

# Available flows:
# - llm continuation (activate for LLM-driven responses)
# - llm generate (explicit generation)

guardrails Module

import guardrails

# Special flows:
# - input rails $input_text
# - output rails $output_text

timing Module

import timing

# Available flows:
# - wait $seconds
# - user was silent $time_s

Best Practices

Always import required modules at the top of your file
Define main flow as the entry point
Use activate for background flows
Name flows descriptively: Past tense for user events, imperative for bot actions
Use the ... operator for dynamic LLM decisions
Add docstrings to document complex flows
Test incrementally as you build

Complete Example: Simple Bot

Here’s a complete bot with greeting, capabilities, and safety:

import core
import llm
import guardrails

flow main
  activate llm continuation
  activate greeting
  activate capabilities

flow greeting
  user expressed greeting
  bot express greeting

flow capabilities
  user asked capabilities
  bot explain capabilities

flow user expressed greeting
  user said "hi"
    or user said "hello"
    or user said "hey"

flow user asked capabilities
  user said "what can you do"
    or user said "help"

flow bot express greeting
  bot say "Hello! I'm your assistant."

flow bot explain capabilities
  bot say "I can answer questions and help you with various tasks. Just ask!"

flow input rails $input_text
  $is_safe = ..."Is this appropriate: '{$input_text}'? Return True or False."
  
  if not $is_safe
    bot say "I can't respond to that."
    abort

Next Steps

Language Reference

Complete Colang 2.0 syntax and features

Migration Guide

Migrate from Colang 1.0 to 2.0

Overview

Learn about Colang 2.0 features

Examples

See more examples

Colang 1.0

Colang 2.0

​Getting Started with Colang 2.0

​Prerequisites

​Hello World

​Your First Script

​Testing

​Adding LLM Support

​LLM-Powered Hello World

​Configuration

​Testing with LLM

​Understanding Flows

​Flow Types

​Flow Syntax

​Flow Events

​Real Example: Interaction Loop

​Adding Guardrails

​Input Rails Example

​The Generation Operator

​Flow Activation

​Working with Variables

​Global Variables

​Keywords Reference

​Core Keywords

​Control Flow

​Operators

​Standard Library Overview

​core Module

​llm Module

​guardrails Module

​timing Module

​Best Practices

​Complete Example: Simple Bot

​Next Steps

Language Reference

Migration Guide

Overview

Examples

Getting Started with Colang 2.0

Prerequisites

Hello World

Your First Script

Testing

Adding LLM Support

LLM-Powered Hello World

Configuration

Testing with LLM

Understanding Flows

Flow Types

Flow Syntax

Flow Events

Real Example: Interaction Loop

Adding Guardrails

Input Rails Example

The Generation Operator

Flow Activation

Working with Variables

Global Variables

Keywords Reference

Core Keywords

Control Flow

Operators

Standard Library Overview

core Module

llm Module

guardrails Module

timing Module

Best Practices

Complete Example: Simple Bot

Next Steps