Registering Custom Actions
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
File-Based Registration
Actions defined in actions.py or the actions/ package are automatically registered when the configuration is loaded.
Single File (actions.py)
Package (actions/)
For larger projects, organize actions in a package:
Programmatic Registration
Register actions dynamically using LLMRails.register_action():
Use Cases for Programmatic Registration
- Runtime configuration:
- Dependency injection:
LangChain Tool Registration
Register LangChain tools as guardrails actions:
Basic Tool Registration
Using Registered Tools in Colang
Multiple Tool Registration
Runnable Registration
Register LangChain Runnables as actions:
Actions Server
For distributed deployments, use an actions server:
Configure the Actions Server URL
Start the Actions Server
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:
Registering Action Parameters
Provide shared resources to actions:
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
2. Group Related Actions
3. Document Your Actions
Related Topics
- Creating Custom Actions - Create your own actions
- Built-in Actions - Default actions in the library
- Action Parameters - Special parameters for actions
- Outbound HTTP - Inject and manage the canonical HTTP client