Feature request: optional external policy-engine example for custom actions

Did you check the docs?

• I have read all the NeMo-Guardrails docs

Is your feature request related to a problem? Please describe.

NeMo Guardrails supports execution rails for controlling custom actions and tool calls, but there is limited runnable guidance showing how to consult an external enterprise policy engine immediately before an action executes.

Enterprise applications may need centrally managed, context-aware decisions based on the authenticated actor, tenant, connector, action, and arguments. They also need to distinguish between actions that are allowed, denied, or require human approval without placing this responsibility in conversational prompts.

A focused example would clarify where the external authorization check belongs, how to prevent execution after a denial, and why require_approval must pause execution rather than grant permission.

This request is for an optional integration example. It does not require changes to the NeMo Guardrails runtime or required dependencies.

Describe the solution you'd like

I would like to contribute a small, optional example demonstrating how NeMo Guardrails can consult an external policy engine before executing a custom action.

The example would use PolicyAware as an optional policy provider and demonstrate three decisions:

• allow: execute the requested action.
• deny: block the action.
• require_approval: do not execute the action; let the host application initiate its approval workflow.

Example scenarios

1. Allow a read-only action

A support agent asks:

Read the account summary for customer C-100.

PolicyAware evaluates the actor, action, and arguments and returns allow. NeMo Guardrails then executes the registered read_customer action and returns its result.

2. Deny a destructive action

A support agent asks:

Delete customer C-100.

PolicyAware returns deny. NeMo Guardrails does not call the delete_customer action and instead responds that the request is not permitted by policy.

3. Require approval for a write action

A support agent asks:

Change customer C-100’s account tier to Gold.

PolicyAware returns require_approval. NeMo Guardrails does not call the update_customer action. The host application can then create a human-approval request and resume the action only after verifying approval.

The intended sequence is:

1. NeMo Guardrails determines that a custom action is requested.
2. An execution flow sends the action name, arguments, and trusted application context to PolicyAware.
3. The flow branches on allow, deny, or require_approval.
4. The custom action runs only when the decision is allow.

NeMo Guardrails would continue to manage conversational rails and action sequencing. PolicyAware would only provide the external policy decision.

The example would be self-contained, require no live policy service, and fail closed if policy evaluation fails. PolicyAware would be installed separately using pip install policyaware; it would not be added to NeMo Guardrails’ required dependencies or lockfile.

I propose placing the example under examples/configs/, but I am happy to use a community documentation page or an externally maintained example if that better matches the project’s contribution style.

I would like to implement this after the issue is triaged and assigned.

Describe alternatives you've considered

I considered the following alternatives:

• External example: Maintain the runnable integration in the PolicyAware repository and link to it from the relevant NeMo Guardrails documentation. This would reduce maintenance for NeMo Guardrails, but users might have more difficulty discovering the example.

• Documentation-only example: Add a short code snippet without runnable files. This would be smaller, but it would not clearly verify that denied and approval-required actions are never executed.

• Application-level wrapper: Perform the policy check entirely in application code outside NeMo Guardrails. This works, but it does not demonstrate how execution flows can govern registered custom actions before execution.

• Package dependency: Add PolicyAware as a required dependency or optional extra. I do not recommend this because the integration should remain optional and isolated from the NeMo Guardrails dependency metadata.

My preferred approach is a small, self-contained runnable example. If maintainers prefer not to include a third-party example, I am happy to maintain it externally and contribute only a documentation link.

Additional context

Relevant project links:

• PolicyAware GitHub: https://github.com/ktirupati/policyaware
• PolicyAware PyPI: https://pypi.org/project/policyaware/
• License: Apache-2.0

The proposed integration is complementary:

• NeMo Guardrails manages conversational rails and action sequencing.
• PolicyAware optionally evaluates whether a proposed action should be allowed, denied, or sent for approval.
• The host application remains responsible for authenticated identity, approval collection, audit retention, and secure execution.

I have prepared an exploratory implementation and deterministic demo covering allow, deny, and require_approval. The demo verifies that only an allowed action executes. It requires no live policy service or API key.

The proposed contribution does not modify the NeMo Guardrails runtime, required dependencies, or dependency lockfile. I am happy to adapt the example’s location, Colang version, terminology, and scope based on maintainer guidance.

I would like to work on this contribution after the issue is triaged and assigned to me.

Start by reviewing the proposed examples/configs/ location and the execution-flow sequence described in the issue. Define the optional PolicyAware integration around custom actions, keeping the provider out of required dependencies. Done means a self-contained deterministic demo covers allow, deny, and require_approval, verifies only allowed actions execute, and fails closed without a live service.