Guards API

Evaluate requests against guards and manage guard rules.

Before you begin

Enable Agent Observability on your Grafana Cloud stack. Refer to Set up Agent Observability in Grafana Cloud.
For configuration changes, use a Grafana identity with permission to manage the relevant resource. Refer to Security and access controls.

For credential requirements, refer to Choose credentials.

Manage guards

Use guard endpoints to evaluate requests synchronously and manage guard rules.

Method	Path	Description
`POST`	`/api/v1/hooks:evaluate`	Evaluate a request against enabled guards.
`GET`	`/api/v1/eval/hook-rules`	List all guard rules.
`POST`	`/api/v1/eval/hook-rules`	Create a guard rule.
`GET`	`/api/v1/eval/hook-rules/{id}`	Get a guard rule by ID.
`PUT`	`/api/v1/eval/hook-rules/{id}`	Update a guard rule.
`DELETE`	`/api/v1/eval/hook-rules/{id}`	Delete a guard rule.

Hook evaluation request

{
  "phase": "preflight",
  "context": {
    "agent_name": "my-agent",
    "model": { "provider": "openai", "name": "gpt-4o" },
    "tags": { "env": "production" }
  },
  "input": {
    "messages": [
      { "role": "user", "parts": [{ "kind": "text", "text": "Hello" }] }
    ],
    "system_prompt": "You are a helpful assistant.",
    "tools": []
  }
}

Hook evaluation response

{
  "action": "allow",
  "rule_id": "redact_pii",
  "transformed_input": null,
  "evaluations": []
}

The action field is allow or deny. When any guard rule applied transforms, transformed_input contains the sanitized copy of the input, and rule_id contains the ID of the first rule that changed the input. rule_id is empty when no transform fired. Each entry in evaluations reports a per-rule outcome with rule_id, evaluator_id, passed, and latency_ms.

Guard rule configuration

{
  "rule_id": "block_tools",
  "enabled": true,
  "phase": "preflight",
  "priority": 5,
  "selector": "all",
  "match": {},
  "evaluator_ids": [],
  "action_on_fail": "deny",
  "tool_filter": { "blocked_names": ["shell_exec", "danger_*"] },
  "redact": {
    "patterns": [
      { "id": "ssn", "regex": "\\b\\d{3}-\\d{2}-\\d{4}\\b" }
    ]
  }
}

Each guard rule must include at least one of these fields: evaluator_ids, redact.patterns, or tool_filter.blocked_names. Redaction matches are always replaced with the fixed token [REDACTED]; free-form replacement text is not accepted.