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.

Note

Using an actions server is optional but highly recommended for production deployments. If no actions server is configured, actions run in the same process as the guardrails server.

For more details on security considerations, see Security Guidelines for LLM Integrations.

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:

Method

Endpoint

Description

GET

/v1/actions/list

List all available actions

POST

/v1/actions/run

Execute an action

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:

[
  "apify",
  "bing_search",
  "google_search",
  "google_serper",
  "openweather_query",
  "searx_search",
  "serp_api_query",
  "wikipedia_query",
  "wolframalpha_query",
  "zapier_nla_query"
]

Python Example#

import requests

actions_server = "http://localhost:8001"

response = requests.get(f"{actions_server}/v1/actions/list")
actions = response.json()

print("Available actions:")
for action in actions:
    print(f"  - {action}")

POST /v1/actions/run#

Execute an action with the specified parameters.

Request Body#

{
  "action_name": "string",
  "action_parameters": {}
}

Field

Type

Description

action_name

string

Name of the action to execute

action_parameters

object

Parameters to pass to the action

Response Body#

{
  "status": "success",
  "result": "string"
}

Field

Type

Description

status

string

Execution status: success or failed

result

string

The result returned by the action

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:

{
  "status": "success",
  "result": "2"
}

Python Example#

import requests

actions_server = "http://localhost:8001"

# Execute an action
response = requests.post(f"{actions_server}/v1/actions/run", json={
    "action_name": "wikipedia_query",
    "action_parameters": {
        "query": "NeMo Guardrails"
    }
})

result = response.json()
if result["status"] == "success":
    print(f"Result: {result['result']}")
else:
    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:

actions_server_url: "http://localhost:8001"

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

rails:
  input:
    flows:
      - 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:

# my_actions.py
from nemoguardrails.actions import action

@action(name="get_weather")
async def get_weather(location: str):
    """Get the current weather for a location."""
    # Your implementation here
    return f"The weather in {location} is sunny."

@action(name="lookup_user")
async def lookup_user(user_id: str):
    """Look up user information."""
    # Your implementation here
    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.

    # config/my-bot/config.yml
actions_server_url: "http://localhost:8001"

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

rails:
  input:
    flows:
      - self check input

  3. Start the guardrails server.

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

  4. Test the servers.

    import requests

# Verify actions are available
actions = requests.get("http://localhost:8001/v1/actions/list").json()
print(f"Available actions: {len(actions)}")

# Chat with the guardrailed model
response = requests.post("http://localhost:8000/v1/chat/completions", json={
    "config_id": "my-bot",
    "messages": [{"role": "user", "content": "What's the weather in New York?"}]
})
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.