> This page is for version v0.24.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/guardrails/_mcp/server.

# Use the Actions Server

> Run guardrail actions in a secure, isolated environment.

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](/resources/guidelines).

## Start the Actions Server

Launch the actions server using the CLI:

```bash
nemoguardrails actions-server [--port PORT]
```

The default port is `8001`.

### Example

```bash
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

```bash
curl http://localhost:8001/v1/actions/list
```

### Response

Returns an array of action names:

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

### Python Example

```python
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

```json
{
  "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

```json
{
  "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

```bash
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:**

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

### Python Example

```python
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`:

```yaml
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:

```python
# 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:

```bash
cd /path/to/my-actions
nemoguardrails actions-server --port 8001
```

Your custom actions are now available:

```bash
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.

   ```bash
   nemoguardrails actions-server --port 8001
   ```

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

   ```yaml
   # 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.

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

4. Test the servers.

   ```python
   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.

## Related Topics

* [Run the Server](/run-guardrailed-inference/using-fastapi-server/run-guardrails-server)
* [Security](/resources/guidelines)
* [Custom Actions](/configure-guardrails/actions)