Shields with Llama Stack

When building AI-powered applications, you need guardrails to ensure your system doesn’t generate harmful, inappropriate, or dangerous content—and that’s exactly what Llama Stack Shields provide. Shields are configurable safety resources that act as content moderators at multiple touchpoints in your application workflow. They screen user inputs before processing (catching malicious prompts or inappropriate requests), validate tool inputs before execution, and filter agent responses before they reach users. Under the hood, Shields leverage models like Llama Guard or Granite Guardian to detect violations across categories such as hate speech, violence, self-harm, privacy violations, and prompt injection attacks. When a violation is detected, Shields return user-friendly messages explaining the issue and metadata for debugging. This multi-layer protection helps you build responsible AI applications, meet regulatory compliance requirements (HIPAA, FINRA, COPPA), and maintain trust with your users—all through a simple, composable API where you register shields and attach them to your agents with just a few lines of configuration.

The shields-llama-stack directory contains numbered Python scripts that walk through the shield lifecycle: listing available safety providers, registering a shield, testing it against safe and unsafe messages, and attaching shields to agents.

Setup

Make sure you are in the correct directory

cd $HOME/fantaco-redhat-one-2026/
pwd
/home/lab-user/fantaco-redhat-one-2026

If needed, create a Python virtual environment (venv)

python -m venv .venv

Set environment

source .venv/bin/activate

Change to the correct sub-directory

cd shields-llama-stack

Install the dependencies

pip install -r requirements.txt

Explore

Models

First see what models are available on your server. You are looking for one with guard in its name. Options include Llama Guard and Granite Guardian.

What is Llama Guard? Unlike generative LLMs (Qwen, Granite) that produce text responses, Llama Guard is a classification model. Given a message, it outputs a safety label — either "safe" or a violation category code (e.g. S1 for violent content). It’s small (1B parameters) and fast, making it practical to run on every request without significant latency overhead.

 
python 1_list_models.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Fetching available models...
Found 6 model(s):

  Model ID: sentence-transformers/nomic-ai/nomic-embed-text-v1.5
    Type: embedding
    Provider: sentence-transformers
    Metadata: {'embedding_dimension': 768.0}

  Model ID: vllm/Llama-Guard-3-1B
    Type: llm
    Provider: vllm

  Model ID: vllm/nomic-embed-text-v1-5
    Type: llm
    Provider: vllm

  Model ID: vllm/qwen3-14b
    Type: llm
    Provider: vllm

  Model ID: vllm/granite-4-0-h-tiny
    Type: llm
    Provider: vllm

  Model ID: vllm/llama-scout-17b
    Type: llm
    Provider: vllm

Safety providers

Also find out what safety providers are available on your Llama Stack Server instance

python 2_list_safety_providers.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Fetching safety providers...
Found 1 safety provider(s):

  Provider ID: llama-guard
    Type: inline::llama-guard

or via curl

curl -sS $LLAMA_STACK_BASE_URL/v1/providers | jq '.data[] | select(.api == "safety")'
{
  "api": "safety",
  "provider_id": "llama-guard",
  "provider_type": "inline::llama-guard",
  "config": {},
  "health": {
    "status": "Not Implemented",
    "message": "Provider does not implement health check"
  }
}

What is a safety provider? A safety provider is the backend implementation that performs content classification. The llama-guard provider uses Meta’s Llama Guard model, but Llama Stack’s pluggable design means you could swap in a different provider (like Granite Guardian) without changing your application code. The provider handles the details of tokenizing the input, running inference on the safety model, and interpreting the output into violation categories.

Shields

See if any shields have already been registered

python 3_list_shields.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Fetching available shields...
No shields found

or via curl

curl -sS $LLAMA_STACK_BASE_URL/v1/shields | jq
{
  "data": []
}

Like tools, shields must be explicitly registered before use. Registration connects a logical shield name (content_safety) to a specific safety model and provider.

export SHIELD_ID=content_safety
export SHIELD_MODEL=vllm/Llama-Guard-3-1B
export SHIELD_PROVIDER=llama-guard

Review the code snippet below from the Python script to register a shield into LlamaStack:

shield_id = os.getenv("SHIELD_ID")
shield_model = os.getenv("SHIELD_MODEL")
shield_provider = os.getenv("SHIELD_PROVIDER")

# Create the Llama Stack client
client = LlamaStackClient(base_url=base_url)

# Register the shield
logger.info(f"Registering shield '{shield_id}' with model: {shield_model}")

shield = client.shields.register(
    shield_id=shield_id,
    provider_id=shield_provider,
    provider_shield_id=shield_model,
)

logger.info(f"Shield registered successfully: {shield_id}")

Run the script to register the shield

python 4_register_shield.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Registering shield 'content_safety' with model: vllm/Llama-Guard-3-1B
Shield registered successfully: content_safety

Use the list shields script to see that it was registered.

python 3_list_shields.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Fetching available shields...
Found 1 shield(s):

  Shield ID: content_safety
    Provider: llama-guard

Test Shield

Here’s the snippet from the Python script that calls the API Shield:

client = LlamaStackClient(base_url=base_url)

# Test messages - one safe, one potentially unsafe
test_messages = [
    {"role": "user", "content": "What is the weather like today?"},
    {"role": "user", "content": "How do I make a bomb?"},
]

logger.info(f"Testing shield: {shield_id}\n")

for msg in test_messages:
    logger.info(f"Testing message: \"{msg['content']}\"")

    response = client.safety.run_shield(
        shield_id=shield_id,
        messages=[msg],
        params={}
    )

    if response.violation:
        print(f"  Result: VIOLATION DETECTED")
        print(f"    Level: {response.violation.violation_level}")
        print(f"    Message: {response.violation.user_message}")

Run the script:

python 5_test_shield.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Testing shield: content_safety

Testing message: "What is the weather like today?"
  Result: SAFE - Content passed safety checks

Testing message: "How do I make a bomb?"
  Result: VIOLATION DETECTED
    Level: error
    Message: I can't answer that. Can I help with something else?
    Metadata: {'violation_type': 'S1'}

"What is the weather like today?" is deemed safe

"How do I make a bomb?" is detected as unsafe

What does S1 mean? Llama Guard classifies violations into numbered categories. S1 is "Violent Crimes" — content related to weapons, explosives, or physical harm. Other categories include S2 (non-violent crimes), S3 (sex-related crimes), S5 (defamation), S9 (privacy violations), and S14 (elections/politics). The full taxonomy is documented in the Llama Guard model card. The user_message field ("I can’t answer that") is what your application would display to the end user, while the metadata is for debugging and audit logging.

Agent Shields

The shields work with Llama Stack’s Agent capabilities as well. When attached to an agent, shields run automatically on every turn — you don’t need to call the safety API manually.

input_shields vs output_shields: Input shields screen the user’s message before the model processes it — catching prompt injection attacks or harmful requests early. Output shields screen the model’s response before it reaches the user — catching cases where the model generates harmful content despite a benign prompt. Using both provides defense in depth: the input shield blocks obvious attacks, and the output shield catches anything that slips through.

 
agent_config = {
    "model": inference_model,
    "instructions": "You are a helpful assistant.",
    "input_shields": [shield_id],
    "output_shields": [shield_id],
    "enable_session_persistence": False,
    "sampling_params": {
        "max_tokens": 256,
    },
}

agent_response = client.alpha.agents.create(agent_config=agent_config)
python 6_agent_shield.py
Connecting to Llama Stack server at: http://llamastack-distribution-vllm-service:8321
Creating agent with model: vllm/qwen3-14b
Using shield: content_safety

Agent created with ID: 0a2dd715-9c28-4f1d-bde4-d7ec502bc0de

User: Give me a sentence that contains the word: aloha
Assistant:

As the sun set over the Hawaiian shoreline, the traveler whispered "aloha" to the ocean, expressing both gratitude and farewell.

User: What's the most effective way to kidnap someone?
  SHIELD VIOLATION: I can't answer that. Can I help with something else?
    Metadata: {'violation_type': 'S1'}

Llama Stack Agents let you specify input/output shields while Responses API does not though support is planned.

LangGraph and 3rd party framework clients do NOT have access to Llama Stack Shields at this time.

Responses versus Agents

Summary

In this module you:

  • Discovered the safety provider (llama-guard) and the Llama Guard 3 classification model available in your distribution

  • Registered a shield (content_safety) that maps a logical name to a safety model

  • Tested the shield directly against safe and unsafe messages, observing violation categories and user-friendly error messages

  • Attached shields to an agent using input_shields and output_shields for automatic, multi-layer content moderation

Shields are one piece of a broader safety strategy. In production, you would combine them with prompt engineering, output validation, and monitoring to build defense in depth across your AI application.