Check NeMo Relay Tool Calls with the Hooks Server
NeMo Relay plugins can register a tool conditional-execution guardrail, which Relay runs before each tool call it manages, with the tool’s name and arguments.
A plugin can forward that check to the Guardrails hooks server (nemoguardrails hooks-server) at /v1/hooks/nemo-relay, so the hooks server’s tool policy and per-tool rails decide whether the call runs.
This page describes the endpoint such a plugin calls.
To install the plugin that calls this endpoint, refer to Check NeMo Relay Tool Calls with the NVIDIA NeMo Guardrails Plugin.
For how Relay runs these guardrails, refer to conditional execution in the NeMo Relay documentation.
Prerequisites
Before you connect your plugin, meet the following prerequisites:
-
NeMo Relay 0.10.1 or later. In 0.10.0, an error from the guardrail let a Claude Code tool call run.
-
A running hooks server. To start one with the NeMo Relay example configuration, run the following command from a clone of the repository:
The example checks an application tool,
search: its tool policy allows onlysearchwith aqueryargument, and a per-tool rail blocks a search whose query is empty, missing, or not a string.
Request
Send POST /v1/hooks/nemo-relay with the three values the guardrail receives:
The endpoint rejects any other field with HTTP 422.
Response
An allowed call returns the following:
A denied call returns the reason, without a prefix:
The reason is the tool policy’s own reason, such as tool call 'search' passes 1 argument its allowed_tools entry doesn't list, or the name of the per-tool rail that blocked the call.
A check that cannot finish returns a non-2xx status with an error body.
For every outcome and error, refer to Hooks Server Results and Errors.
For the endpoint’s full reference, refer to Hooks Server API: Check a NeMo Relay Tool Call.
Map the Response to the Guardrail Result
The plugin returns the hooks server’s answer as the guardrail callback’s result:
Map every failure to Err, never to Ok(None), so the plugin never reports a check that could not finish as an allow.
What Relay then does with the call depends on the integration that runs the agent:
- Relay’s Claude Code and Codex integrations block the call on
Errfrom Relay 0.10.1. Through the Relay CLI’s gateway, the agent receives the plugin’s error inside Relay’s message. Through the managed Relay daemon, the agent receives only Relay’s own message. Refer to Check NeMo Relay Tool Calls with the NVIDIA NeMo Guardrails Plugin: Find the Reason for a Failed Check. - Relay’s standalone pi extension treats
Erras a fault and lets the call run by default, withNEMO_RELAY_PI_FAIL=open. SetNEMO_RELAY_PI_FAIL=closedto block the call. - Relay’s managed pi extension blocks the call on
Errand does not useNEMO_RELAY_PI_FAIL.
Tool Names
Relay forwards the names of whatever tools it wraps, and the hooks server matches them exactly. Behind Relay’s Claude Code or Codex integration, the names are that agent’s, so base the configuration on the Claude Code or Codex tool names.
Check Each Call Once
Account for the following sources of duplicate checks:
- Use Relay or a direct agent hook, not both. With a Relay plugin and a direct Claude Code or Codex hook both pointed at hooks servers, every call is checked twice.
- Relay 0.10 checks some calls twice.
Through the 0.10 releases, Relay also runs the guardrail on Claude Code’s and Codex’s
PermissionRequestevent. A call that reaches a permission prompt then costs two requests to the hooks server, and two runs of any rail that calls a model. When the second check allows the call, Relay also approves Claude Code’s permission prompt, so Claude Code does not ask the user.