Use the Actions Server

The Actions Server enables you to run actions invoked from guardrails in a secure, isolated environment separate from the main guardrails server.

Why Use an Actions Server?

Actions are custom Python functions that guardrails can invoke during processing. Running actions in a separate server provides:

• Security isolation: Actions run in a separate process, limiting the impact of potentially unsafe code.
• Resource management: Separate resource allocation for action execution.
• Scalability: Scale the actions server independently from the guardrails server.

For more details on security considerations, see Security.

Start the Actions Server

Launch the actions server using the CLI:

$
nemoguardrails actions-server [--port PORT]

The default port is 8001.

Example

$
nemoguardrails actions-server --port 8001

On startup, the actions server automatically registers:

• All predefined actions from the NeMo Guardrails library.
• All actions defined in Python files in the current folder and sub-folders.

Endpoints

The actions server exposes two endpoints:

View the OpenAPI documentation at:

• Swagger UI: http://localhost:8001/docs
• ReDoc: http://localhost:8001/redoc

GET /v1/actions/list

List all available actions registered with the server.

Request

$
curl http://localhost:8001/v1/actions/list

Response

Returns an array of action names:

1
[
2
  "apify",
3
  "bing_search",
4
  "google_search",
5
  "google_serper",
6
  "openweather_query",
7
  "searx_search",
8
  "serp_api_query",
9
  "wikipedia_query",
10
  "wolframalpha_query",
11
  "zapier_nla_query"
12
]

Python Example

1
import requests
2
3
actions_server = "http://localhost:8001"
4
5
response = requests.get(f"{actions_server}/v1/actions/list")
6
actions = response.json()
7
8
print("Available actions:")
9
for action in actions:
10
    print(f"  - {action}")

POST /v1/actions/run

Execute an action with the specified parameters.

Request Body

1
{
2
  "action_name": "string",
3
  "action_parameters": {}
4
}

Response Body

1
{
2
  "status": "success",
3
  "result": "string"
4
}

Example: Wolfram Alpha Query

$
curl -X POST http://localhost:8001/v1/actions/run \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "action_name": "wolframalpha_query",
>
    "action_parameters": {
>
      "query": "What is the largest prime factor of 1024?"
>
    }
>
  }'

Response:

1
{
2
  "status": "success",
3
  "result": "2"
4
}

Python Example

1
import requests
2
3
actions_server = "http://localhost:8001"
4
5
# Execute an action
6
response = requests.post(f"{actions_server}/v1/actions/run", json={
7
    "action_name": "wikipedia_query",
8
    "action_parameters": {
9
        "query": "NeMo Guardrails"
10
    }
11
})
12
13
result = response.json()
14
if result["status"] == "success":
15
    print(f"Result: {result['result']}")
16
else:
17
    print("Action failed")

Configure Guardrails to Use the Actions Server

To configure a guardrails configuration to use a remote actions server, add the actions_server_url to your config.yml:

1
actions_server_url: "http://localhost:8001"
2
3
models:
4
  - type: main
5
    engine: openai
6
    model: gpt-4
7
8
rails:
9
  input:
10
    flows:
11
      - self check input

When configured, the guardrails server sends action execution requests to the actions server instead of running them locally.

Register Custom Actions

The actions server automatically discovers actions in the current directory. Create a Python file with your custom actions:

1
# my_actions.py
2
from nemoguardrails.actions import action
3
4
@action(name="get_weather")
5
async def get_weather(location: str):
6
    """Get the current weather for a location."""
7
    # Your implementation here
8
    return f"The weather in {location} is sunny."
9
10
@action(name="lookup_user")
11
async def lookup_user(user_id: str):
12
    """Look up user information."""
13
    # Your implementation here
14
    return {"name": "Alice", "id": user_id}

Start the actions server from the directory containing your actions:

$
cd /path/to/my-actions
$
nemoguardrails actions-server --port 8001

Your custom actions are now available:

$
curl http://localhost:8001/v1/actions/list
$
# ["get_weather", "lookup_user", "apify", "bing_search", ...]

Example: Complete Workflow

This example demonstrates running both servers together.

1. Start the Actions Server.

   $
   nemoguardrails actions-server --port 8001

2. Configure a guardrails configuration to use the actions server.

   1
   # config/my-bot/config.yml
   2
   actions_server_url: "http://localhost:8001"
   3
   4
   models:
   5
     - type: main
   6
       engine: openai
   7
       model: gpt-4
   8
   9
   rails:
   10
     input:
   11
       flows:
   12
         - self check input

3. Start the guardrails server.

   $
   nemoguardrails server --config ./config --port 8000

4. Test the servers.

   1
   import requests
   2
   3
   # Verify actions are available
   4
   actions = requests.get("http://localhost:8001/v1/actions/list").json()
   5
   print(f"Available actions: {len(actions)}")
   6
   7
   # Chat with the guardrailed model
   8
   response = requests.post("http://localhost:8000/v1/chat/completions", json={
   9
       "config_id": "my-bot",
   10
       "messages": [{"role": "user", "content": "What's the weather in New York?"}]
   11
   })
   12
   print(response.json())

Deployment Considerations

For production deployments:

1. Network isolation: Deploy the actions server in a separate network segment.
2. Authentication: Add authentication between the guardrails and actions servers.
3. Resource limits: Configure appropriate resource limits for action execution.
4. Monitoring: Monitor action execution times and failure rates.
5. Logging: Enable detailed logging for debugging and auditing.

Related Topics

• Run the Server
• Security
• Custom Actions