Skip to navigation

Registering Custom Actions

View as MarkdownOpen in Claude

This section describes the different ways to register custom actions with the NeMo Guardrails library.

Custom actions run only on LLMRails. The IORails engine does not load or call them. For the other parts of a configuration that the IORails engine ignores, refer to Migrating to 0.25: What IORails Ignores in a Configuration.

Registration Methods

MethodDescriptionUse Case
File-basedActions in actions.py are auto-registeredStandard configurations
ProgrammaticRegister via LLMRails.register_action()Dynamic registration
LangChain toolsRegister LangChain tools as actionsTool integration
Actions serverRemote action executionDistributed systems

File-Based Registration

Actions defined in actions.py or the actions/ package are automatically registered when the configuration is loaded.

Single File (actions.py)

config/
├── config.yml
├── actions.py # Actions auto-registered
└── rails/
└── ...
# config/actions.py
from nemoguardrails.actions import action
@action()
async def my_action():
return "result"
@action(name="custom_name")
async def another_action():
return "another result"

Package (actions/)

For larger projects, organize actions in a package:

config/
├── config.yml
├── actions/
│ ├── __init__.py
│ ├── validation.py
│ ├── external.py
│ └── utils.py
└── rails/
└── ...
# config/actions/__init__.py
from .validation import check_input, check_output
from .external import fetch_data, call_api
# config/actions/validation.py
from nemoguardrails.actions import action
@action()
async def check_input(text: str):
return len(text) > 0
@action()
async def check_output(text: str):
return "error" not in text.lower()

Programmatic Registration

Register actions dynamically using LLMRails.register_action():

from nemoguardrails import LLMRails, RailsConfig
config = RailsConfig.from_path("config")
rails = LLMRails(config)
# Register a function as an action
async def my_dynamic_action(param: str):
return f"Processed: {param}"
rails.register_action(my_dynamic_action, name="dynamic_action")

Use Cases for Programmatic Registration

  1. Runtime configuration:
def setup_rails(environment: str):
config = RailsConfig.from_path("config")
rails = LLMRails(config)
if environment == "production":
rails.register_action(production_validator, "validate")
else:
rails.register_action(dev_validator, "validate")
return rails
  1. Dependency injection:
class DatabaseService:
async def query(self, sql: str):
# Database query logic
pass
db = DatabaseService()
async def db_query_action(query: str):
return await db.query(query)
rails.register_action(db_query_action, name="query_database")

LangChain Tool Registration

Register LangChain tools as guardrails actions:

Basic Tool Registration

from langchain_core.tools import tool
from nemoguardrails import LLMRails, RailsConfig
@tool
def get_weather(city: str) -> str:
"""Get weather for a city."""
return f"Weather in {city}: Sunny, 72°F"
config = RailsConfig.from_path("config")
rails = LLMRails(config)
# Register the tool as an action
rails.register_action(get_weather, name="get_weather")

Using Registered Tools in Colang

define flow weather_flow
user ask about weather
$weather = execute get_weather(city=$city_name)
bot provide weather info

Multiple Tool Registration

from langchain_core.tools import tool
@tool
def search_web(query: str) -> str:
"""Search the web."""
return f"Results for: {query}"
@tool
def get_current_time(timezone: str) -> str:
"""Get the current time."""
return f"Current time in {timezone}: 12:00 PM"
# Register multiple tools
tools = [search_web, get_current_time]
for t in tools:
rails.register_action(t, name=t.name)

Runnable Registration

Register LangChain Runnables as actions:

from langchain_core.runnables import RunnableLambda
from nemoguardrails import LLMRails, RailsConfig
# Create a runnable
process_text = RunnableLambda(lambda x: x.upper())
config = RailsConfig.from_path("config")
rails = LLMRails(config)
# Register the runnable
rails.register_action(process_text, name="process_text")

Actions Server

For distributed deployments, use an actions server:

Configure the Actions Server URL

# config.yml
actions_server_url: http://actions-server:8001

Start the Actions Server

nemoguardrails actions-server --config config/

Actions Server Benefits

  • Centralized action management
  • Horizontal scaling
  • Separation of concerns
  • Easier updates without redeploying the main service

Registration in config.py

Use config.py for custom initialization including action registration:

# config/config.py
from nemoguardrails import LLMRails
def init(app: LLMRails):
"""Custom initialization function."""
# Register actions
async def custom_action(param: str):
return f"Custom: {param}"
app.register_action(custom_action, name="custom_action")
# Register action parameters
db_connection = create_db_connection()
app.register_action_param("db", db_connection)

Registering Action Parameters

Provide shared resources to actions:

# config/config.py
def init(app: LLMRails):
# Create shared resources
cache = RedisCache()
# Register as action parameters
app.register_action_param("cache", cache)
# config/actions.py
from nemoguardrails.actions import action
from nemoguardrails.http import HTTPClient, http_call
@action()
async def fetch_with_cache(
url: str,
cache=None,
http_client: HTTPClient | None = None,
):
# Check cache first
cached = await cache.get(url)
if cached:
return cached
# Fetch and cache
response = await http_call(http_client, "GET", url)
data = response.json()
await cache.set(url, data)
return data

An injected HTTP client remains caller-owned and must be closed by the application that created it. For the shared-client lifecycle pattern, refer to Outbound HTTP in Actions.

Best Practices

1. Use Descriptive Names

# Good
@action(name="validate_user_age")
async def validate_age(age: int):
pass
# Avoid
@action(name="v_a")
async def validate_age(age: int):
pass
actions/
├── __init__.py
├── validation/
│ ├── __init__.py
│ ├── input.py
│ └── output.py
├── external/
│ ├── __init__.py
│ ├── weather.py
│ └── search.py
└── utils.py

3. Document Your Actions

@action()
async def search_knowledge_base(
query: str,
top_k: int = 5
) -> list:
"""
Search the knowledge base for relevant documents.
Args:
query: The search query string
top_k: Maximum number of results to return
Returns:
List of relevant document snippets
"""
pass