Core Controls

Deterministic seed, cooperative cancel, tool-arg validation, and PII redaction — four production switches with one-line opt-in.

Four small switches that make a PraisonAI agent safer, more deterministic, and easier to interrupt in production.

The user starts a run; core controls enforce safety policies during execution.

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="Run with guardrails, interrupts, and validation enabled",
)

agent.start("Execute this task safely")

Quick Start

1. PII Redaction

   from praisonaiagents import Agent
   from praisonaiagents.trace import enable_pii_redaction
   
   enable_pii_redaction()  # idempotent; safe to call multiple times
   
   agent = Agent(
       name="helper",
       instructions="You are a concise assistant.",
       llm={"model": "gpt-4o-mini"},
   )
   print(agent.chat("My api_key=sk-XYZ — what is 2+2?"))
   
2. Deterministic Seed & Cancellation

   from praisonaiagents import Agent
   from praisonaiagents.agent.interrupt import InterruptController
   
   agent = Agent(name="helper", instructions="You are a concise assistant.", llm={"model": "gpt-4o-mini"})
   tok = InterruptController()
   
   reply = agent.chat("Pick a number 1-100.", seed=42, cancel_token=tok)
   
3. Tool Validation

   from praisonaiagents import Agent
   from praisonaiagents.tools.validators import ValidationResult
   
   class RangeValidator:
       def validate_args(self, tool_name, args, context=None):
           if tool_name == "set_temperature" and not 0 <= args.get("value", 0) <= 100:
               return ValidationResult(valid=False, errors=["temperature 0-100"])
           return ValidationResult(valid=True)
       def validate_result(self, tool_name, result, context=None):
           return ValidationResult(valid=True)
   
   def set_temperature(value: float) -> str:
       return f"set to {value}"
   
   agent = Agent(name="thermostat", tools=[set_temperature], llm={"model": "gpt-4o-mini"})
   agent._tool_validator = RangeValidator()
   print(agent.chat("Set the temperature to 500"))
   

---

How It Works

---

Configuration Options

Option	Type	Default	Description
seed	int | None	None	Per-call random seed forwarded to the LLM. Overrides any seed set on the LLM instance for this call only.
cancel_token	InterruptController | None	None	Cooperative cancellation token. When is_set() returns true at a checkpoint, raises InterruptedError(reason). Falls back to agent.interrupt_controller if not provided. Threaded through both the LiteLLM and OpenAI-native paths for sync chat(); async achat() currently only honours it on the LiteLLM path.

---

Deterministic seed

Per-call determinism for reproducible outputs.

from praisonaiagents import Agent

agent = Agent(
    name="helper",
    instructions="You are a concise assistant.",
    llm={"model": "gpt-4o-mini"},
)

# Same seed → same model output (provider-permitting)
print(agent.chat("Pick a number 1-100", seed=42))
print(agent.chat("Pick a number 1-100", seed=42))

---

Cooperative cancellation

Thread-safe cancellation without hard kills.

Fixed in PR #2751 (release after 2026-07-07): earlier releases only checked cancel_token on the OpenAI completion path in chat_mixin. The litellm-backed tool loop in llm/llm.py (used for Anthropic, Gemini, Groq, local models, and any non-OpenAI provider) took no cancel token and performed no checkpoint, so /stop and InterruptController.request() were silently no-ops on those providers. Upgrade to get uniform cancellation across every provider.

Tightened in PR #2997 (release after 2026-07-14): every tool-loop iteration now checks cancel_token.is_set() twice — at the top of the iteration and again immediately before dispatching tool calls — in both LiteLLM (llm/llm.py) and OpenAI-native (llm/openai_client.py) paths, sync and async. This closes a window where a /stop arriving between the model returning tool calls and the tools starting could still execute one round of tools before honouring the cancel.

Fixed in PR #4301 (release after 2026-08-24): the between-iteration cancel checks documented above were previously never armed on the default OpenAI-native sync path. chat_mixin._chat_completion did not accept cancel_token, so the token was dropped between the agent and OpenAIClient.chat_completion_with_tools. Result: /stop on a plain Agent(...) or Agent(llm="gpt-4o-mini") reported ”✅ Current task cancelled” while every remaining tool call kept executing and chat() returned its normal final answer.

PR #4301 threads cancel_token through the four sync hops (_chat_completion → _chat_completion_with_retry → _execute_unified_chat_completion → _unified_dispatcher.chat_completion), so a /stop on the default path now halts between tool iterations exactly as documented. Any model string containing / (LiteLLM path) was already working via PR #2751.

Async default-path still needs threading. PR #4301 covers only the sync path. The async twin _achat_impl has the same shape and the same dropped-token defect — await agent.achat(..., cancel_token=tok) on the default OpenAI-native path will still run its tool loop to completion. Use the sync chat(...) entry point, or route through a provider/model string (LiteLLM path, already fixed by PR #2751) if you need cancellation from achat() today. Tracking follow-up in PR #4301 discussion.

Extended in PR #4248: sync Agent.chat() with a managed backend now honours the cancel token before the backend call, matching achat().

import threading
from praisonaiagents import Agent
from praisonaiagents.agent.interrupt import InterruptController

agent = Agent(name="worker", instructions="You are a helpful assistant.", llm={"model": "gpt-4o-mini"})
tok = InterruptController()

def do_work():
    try:
        print(agent.chat("Write a long essay about Rome.", cancel_token=tok))
    except InterruptedError as e:
        print(f"Aborted cleanly: {e}")

threading.Thread(target=do_work).start()
# … later, from any thread:
tok.request("user pressed stop")

---

Tool argument validation

Validate tool arguments before execution.

from praisonaiagents import Agent
from praisonaiagents.tools.validators import ValidationResult

class RangeValidator:
    def validate_args(self, tool_name, args, context=None):
        if tool_name == "set_temperature" and not 0 <= args.get("value", 0) <= 100:
            return ValidationResult(
                valid=False,
                errors=["temperature must be between 0 and 100"],
                remediation="Use a value in the 0-100 range.",
            )
        return ValidationResult(valid=True)

    def validate_result(self, tool_name, result, context=None):
        return ValidationResult(valid=True)

def set_temperature(value: float) -> str:
    return f"set to {value}"

agent = Agent(name="thermostat", tools=[set_temperature], llm={"model": "gpt-4o-mini"})
agent._tool_validator = RangeValidator()

print(agent.chat("Set the temperature to 500"))  # validator rejects, tool never runs

ValidationResult fields:

Field	Type	Description
valid	bool	Whether validation passed
errors	List[str]	List of error messages
warnings	List[str]	List of warning messages
remediation	Optional[str]	Suggested fix for validation errors

---

PII redaction

Scrub sensitive data from LLM requests.

1. Enable once at startup

   from praisonaiagents.trace import enable_pii_redaction
   enable_pii_redaction()  # idempotent — safe to call many times
   
2. Use agents normally

   Every BEFORE_LLM event now passes messages through the scrubber.

3. Disable in tests if needed

   from praisonaiagents.trace import disable_pii_redaction
   disable_pii_redaction()
   

Since PraisonAI PR #3908, enable_pii_redaction() — and any other BEFORE_LLM / AFTER_LLM hook — now fires on both agent.chat() and agent.achat(). Earlier releases fired the hook on sync chat() only, so async workflows silently sent unscrubbed prompts to the provider. If your production path went async, upgrade before relying on the redactor.

What gets scrubbed:

• Key=value pairs: api_key=sk-…, password: hunter2, token=… → [REDACTED]
• Naked tokens: OpenAI-style sk-ABCDEF… keys → [REDACTED]
• Identifiers: US SSNs 123-45-6789 → [REDACTED-SSN], credit cards → [REDACTED-CC], emails → [REDACTED-EMAIL]

---

Which one do I use?

---

Common Patterns

Reproducible eval

from praisonaiagents import Agent

agent = Agent(name="eval", instructions="Pick a random number 1-100", llm={"model": "gpt-4o-mini"})

# Same seed should give same output
response1 = agent.chat("Pick a number", seed=42)
response2 = agent.chat("Pick a number", seed=42)
assert response1 == response2  # Should pass with most providers

Cancel from Ctrl+C handler

import signal
from praisonaiagents import Agent
from praisonaiagents.agent.interrupt import InterruptController

agent = Agent(name="worker", instructions="You are helpful", llm={"model": "gpt-4o-mini"})
tok = InterruptController()

def signal_handler(signum, frame):
    tok.request("sigint")

signal.signal(signal.SIGINT, signal_handler)

try:
    result = agent.chat("Write a very long essay", cancel_token=tok)
    print(result)
except InterruptedError as e:
    print(f"Cancelled: {e}")

Disable redaction in tests

import pytest
from praisonaiagents.trace import enable_pii_redaction, disable_pii_redaction

@pytest.fixture(autouse=True)
def test_redaction():
    # Enable for production-like behavior
    enable_pii_redaction()
    yield
    # Clean up after test
    disable_pii_redaction()

---

Best Practices

Seed reliability

Some providers ignore seed or treat it as best-effort. Don’t rely on it for production routing decisions.

Thread-safe cancellation

InterruptController.request(...) is thread-safe. Trip it from a signal handler, an HTTP cancel endpoint, or a parent supervisor.

Fast validators

Validators run on every tool invocation. Avoid network calls or heavy work — return fast ValidationResult objects.

Local audit trail

enable_pii_redaction() only scrubs messages going to the LLM. Your local chat history still has the raw prompt — keep it secure or scrub it separately.

---

Related

Approval

Human-in-the-loop approvals for sensitive operations

Guardrails

Input and output validation with custom rules

Security Environment Variables

Secure handling of API keys and secrets

Hooks

Event system for BEFORE_LLM and BEFORE_TOOL hooks

BEFORE_LLM on async

BEFORE_LLM / AFTER_LLM fire on both chat() and achat()