Configuring Custom Actions

This section guides you through how to create the actions.py file to define custom Python actions and integrate them into the NeMo Guardrails library. By configuring custom actions, you can execute Python code within guardrails flows, extending the library with custom logic, external API integrations, and complex validation.

An actions.py file defines custom action functions using the @action decorator. A decorator is a callable that takes a function and returns a new function, usually adding behavior or attaching metadata.

from typing import Optional
from nemoguardrails.actions import action
@action()
async def check_custom_policy(context: Optional[dict] = None):
    """Check if the input complies with custom policy."""
    user_message = context.get("last_user_message", "")
    # Custom validation logic
    forbidden_words = ["spam", "phishing"]
    for word in forbidden_words:
        if word in user_message.lower():
            return False
    return True
@action(name="fetch_user_data")
async def get_user_info(user_id: str):
    """Fetch user data from external service."""
    # External API call
    return {"user_id": user_id, "status": "active"}

Configuration Sections

The following sections provide detailed documentation for creating and using custom actions:

Creating Actions

Create custom actions using the @action decorator to integrate Python logic.

How To

Built-in Actions

Reference for default actions included in the NeMo Guardrails library.

Reference

Action Parameters

Reference for special parameters like context, llm, and config provided to actions.

Return engine-neutral allow, block, and transform decisions from rail actions, including migration from output_mapping.

Reference

Outbound HTTP

Use the canonical HTTP client for lifecycle management, retries, observability, and deterministic tests.

How To

File Organization

Custom actions can be organized in two ways:

Option 1: Single actions.py file

.
├── config
│   ├── config.yml
│   ├── actions.py        # All custom actions
│   └── rails/
│       └── ...

Option 2: actions/ sub-package

.
├── config
│   ├── config.yml
│   ├── actions/
│   │   ├── __init__.py
│   │   ├── validation.py
│   │   ├── external_api.py
│   │   └── ...
│   └── rails/
│       └── ...

Quick Example

1. Define the Action

Create config/actions.py:

from typing import Optional
from nemoguardrails.actions import action
@action(is_system_action=True)
async def check_blocked_terms(context: Optional[dict] = None):
    """Check if bot response contains blocked terms."""
    bot_response = context.get("bot_message", "")
    blocked_terms = ["confidential", "proprietary", "secret"]
    for term in blocked_terms:
        if term in bot_response.lower():
            return True  # Term found, block the response
    return False  # No blocked terms found

2. Create a Flow Using the Action

Create config/rails/output.co:

define bot refuse to respond
  "I apologize, but I cannot provide that information."
define flow check_output_terms
  $contains_blocked = execute check_blocked_terms
  if $contains_blocked
    bot refuse to respond
    stop

3. Configure the Rail

Add to config/config.yml:

rails:
  output:
    flows:
      - check_output_terms

For detailed information about each topic, refer to the individual pages linked above.