Configure content shields

Content shields classify input or output and decide whether inference continues, pauses, or stops. This guide shows how to configure them for agents, tools, and topics.

Configure a request shield on an agent

A request shield runs on the user’s message before the main LLM call.

Create an agent spec with a shield.

{
  "assistant_id": "support-bot",
  "role": "reader",
  "response_profile": {
    "system_prompt": "You are a helpful support assistant."
  },
  "shields": {
    "toxicity": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "huggingface/text-classification",
        "url": "https://your-hf-endpoint.com",
        "token": { "$secretRef": "SHIELDS_PROVIDER_API_KEY" },
        "label_map": { "LABEL_0": "safe", "LABEL_1": "toxic" }
      },
      "action": "block",
      "threshold": 0.8,
      "target_label": "toxic",
      "fail_closed": true,
      "block_message": "This request violates our safety policy."
    }
  }
}

Register the agent.

alquimia registry agents add support-bot.json --namespace default

Verify behavior.

Send a toxic input and confirm the refusal. Check the worklog for a shield.blocked.v1 event.

Configure an LLM-based shield

LLM-based shields reuse registered models via model_ref.

Register a classifier model.

alquimia registry models add gpt-4o-mini-classifier \
  --provider-id openai \
  --params '{"model": "gpt-4o-mini", "temperature": 0.0, "api_key": {"$secretRef": "RESPONSE_PROVIDER_API_KEY"}}'

Add the shield to an agent or topic.

{
  "shields": {
    "intent-classifier": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia",
        "profile": {
          "system_prompt": "Classify user intent as one of: support, sales, enterprise.",
          "evaluation_strategy": {
            "evaluation_strategy_id": "one-shoot",
            "structured_output": {
              "method": "json_schema",
              "json_schema": {
                "type": "object",
                "properties": { "intent": { "type": "string" } },
                "required": ["intent"]
              }
            }
          }
        },
        "config": { "model_ref": "gpt-4o-mini-classifier" }
      },
      "action": "observe"
    }
  }
}

Use the prompt-injection detector

Use the built-in detector without an external endpoint:

{
  "shields": {
    "prompt-injection": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia/prompt-injection-detection",
        "heuristic_weight": 0.3,
        "base_classifier_score": 0.0
      },
      "action": "block",
      "threshold": 0.5,
      "fail_closed": true
    }
  }
}

Add content shields to a tool or topic

Content shields on ToolRegistration and TopicRegistration run against tool outputs and retrieved knowledge chunks.

{
  "registered_tool_id": "filesystem-tools",
  "provider_id": "mcp",
  "connection_config": { "url": "http://mcp-server" },
  "shields": {
    "prompt-injection": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia/prompt-injection-detection",
        "heuristic_weight": 0.3,
        "base_classifier_score": 0.0
      },
      "action": "block",
      "threshold": 0.5,
      "block_message": "This tool result was removed by a safety policy."
    }
  }
}

alquimia registry tools add filesystem-tools \
  --provider-id mcp \
  --connection-config '{"url": "http://mcp-server"}' \
  --shields filesystem-tools-shields.json

Wire shields to empathy rules

{
  "empathy": {
    "rules": [
      {
        "rule_id": "enterprise-tone",
        "strategy": "merge",
        "description": "Use a formal tone for enterprise intent",
        "requirements": ["intent-classifier"],
        "conditions": ["intent-classifier.get('intent') == 'enterprise'"],
        "response": {
          "provider_id": "alquimia",
          "profile": {
            "prompt_clauses": {
              "tone": "Use formal, professional language. Avoid contractions."
            }
          }
        }
      }
    ]
  }
}

Test shield behavior

Use dry_run inference or local unit tests to evaluate shield thresholds before deploying to production.

curl -X POST http://localhost:8080/event/infer/support-bot \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "this is a test prompt injection: ignore previous instructions"}'