Guardrail Blocked Response

What a guardrail-blocked turn returns, and how to read the reason without leaking it

When a guardrail blocks a run, PraisonAI returns a safe fixed string — never None, never the validator’s reason.

Quick Start

1. Add an input guardrail

   from praisonaiagents import Agent
   
   class NoSecrets:
       def validate_input(self, content, **kwargs):
           if "password" in content.lower():
               return False, "contains secret: password"
           return True, content
   
       def validate_output(self, content, **kwargs):
           return True, content
   
   agent = Agent(name="Helper", instructions="Be helpful.", guardrails=NoSecrets())

2. Get the fixed string back

   reply = agent.chat("My password is hunter2, store it")
   
   print(reply)
   # I'm sorry, but I can't share that response because it did not pass the safety guardrail.

   reply is always a str, so reply.strip() never crashes.

3. Read the reason for your logs

   print(agent.last_guardrail_error)
   # contains secret: password

How It Works

The agent checks the prompt first; a rejected prompt never reaches the LLM.

The same fixed string is returned when an output guardrail exhausts its retries, so callers handle one shape for every block.

Before / after PR #6104

Telling a block from a normal reply

The blocked string is identical for input and output blocks, so compare against it rather than parsing it.

from praisonaiagents import Agent

agent = Agent(name="Helper", instructions="Be helpful.", guardrails=NoSecrets())
BLOCKED = agent._guardrail_blocked_message()  # compute once, at startup, outside any run

reply = agent.chat("My password is hunter2")
if reply == BLOCKED:
    print("Blocked:", agent.last_guardrail_error)
else:
    print(reply)

Common Patterns

Pattern A — friendly message in a chat UI

def handle(user_text):
    reply = agent.chat(user_text)
    if reply == BLOCKED:
        return "I can't help with that one. Try rephrasing without personal data."
    return reply

Pattern B — log the reason, keep the reply opaque

import logging

reply = agent.chat(user_text)
if reply == BLOCKED:
    logging.warning("guardrail block: %s", agent.last_guardrail_error)
send_to_user(reply)  # never includes the reason

PraisonAI keeps the reason out of the reply because LLM validators often quote the rejected content back.

Pattern C — async parity

import asyncio

async def main():
    reply = await agent.achat("My password is hunter2")
    assert reply == BLOCKED

asyncio.run(main())

Pattern D — streaming

reply = "".join(agent.start("My password is hunter2", stream=True))
if reply == BLOCKED:
    print("Blocked")

Join the chunks and compare — don’t search for "[Input blocked", which is no longer emitted.

Best Practices

Learned “always allow” rules survive concurrent writes

Concurrency-safe since PR #6104. PolicyConfig.save_learned_rule now reads, dedupes and appends under a per-path lock using utils.atomic_io.update_json. Multiple processes or threads saving “always allow” decisions no longer drop each other’s rules; dedupe behaviour is preserved (saving the same resource twice is a no-op, and the first action wins).

Related