Skip to content

Shield blocks

Shields classify content and decide whether inference continues. When a blocking shield triggers, the worklog records a shield.blocked.v1 event.

Request blocked before inference

A shield with action: "block" that crosses its threshold terminates inference and returns a refusal.

Common causes:

The input matched target_label with a score above threshold.
The shield could not reach its provider and fail_closed: true was set.
A heuristic shield such as alquimia/prompt-injection-detection flagged the input.

Tool or topic result replaced

Content shields attached to ToolRegistration or TopicRegistration do not abort the turn. Instead, the offending result is replaced with block_message and a shield.blocked.v1 event is recorded.

Inspect the worklog

curl "http://localhost:8080/worklog/task-abc123/events" \
  -H "Authorization: Bearer $API_TOKEN"

Look for:

shield_id
label and score
action taken (block or replace)
block_message

Tune the shield

Knob	Effect
`threshold`	Higher values make the shield less sensitive
`target_label`	Restrict blocking to a single predicted label
`fail_closed`	Set to `false` if transient provider failures should not block
`action`	Use `observe` or `flag` while tuning, then switch to `block`

Example: lower sensitivity

{
  "shields": {
    "toxicity": {
      "provider_id": "shield-config",
      "connector": { "provider_id": "huggingface/text-classification", "url": "..." },
      "action": "block",
      "threshold": 0.9,
      "target_label": "toxic",
      "fail_closed": true
    }
  }
}