Prompt Injection Protection

Web search and other external tools wrap results in safety markers — the model treats them as data, not instructions.

from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo

agent = Agent(
    name="Researcher",
    instructions="Research topics safely",
    tools=[duckduckgo],
)

agent.start("Find recent AI safety papers")
# duckduckgo results auto-wrapped in <external_tool_result> markers

The user searches the web; external tool output is wrapped so the model treats it as data.

The hook-layer scanner protects agent prompts and tool outputs. The agent↔agent boundary is protected separately by the Inter-Agent Provenance envelope — enabled by default on every create_subagent_tool call.

Quick Start

Simple Usage

Built-in search tools are protected automatically:

from praisonaiagents import Agent
from praisonaiagents.tools import duckduckgo

agent = Agent(
    name="Researcher",
    instructions="Research topics safely",
    tools=[duckduckgo],
)

agent.start("Find recent AI safety papers")

With Configuration

Mark custom tools as external:

from praisonaiagents import Agent, register_tool

def my_web_lookup(query: str) -> str:
    """Fetch data from an external API."""
    return fetch_from_api(query)

register_tool(my_web_lookup, name="my_web_lookup", trust_level="external")

agent = Agent(
    name="Researcher",
    instructions="Use my_web_lookup for facts",
    tools=["my_web_lookup"],
)

add_external_tool is now safe to call at any time. It mutates the module-level EXTERNAL_TOOL_NAMES set in place, so a module that imported the name earlier still sees the addition — the previous frozenset+rebind behaviour could leave importers holding a stale, pre-registration copy. Fixed in PR #4969.

How It Works

Auto-protected built-ins include duckduckgo, web_search, tavily_search, scrape_page, fetch_url, and others in the external tools set. MCP tools can be marked at registration time. Outbound tool results are wrapped in <external_tool_result>; inbound webhook and hook payloads are wrapped in <external_request_payload> — same idea, opposite direction. See Untrusted Request Fencing for the ingress boundary.

Condition	Action
Trusted tool	Result unchanged
External + string ≥ 32 chars	Wrapped in `<external_tool_result>`
External + string < 32 chars	Unchanged (overhead skip)
External + dict/list	JSON-serialised then wrapped
Inbound webhook / hook payload	Wrapped in `<external_request_payload>` at ingress

What happens if the trust decision fails

When the trust registry exists but raises while answering a trust lookup, PraisonAI now fails closed: the tool is treated as external and its result is fenced. Under-fencing an external tool is the exact bug the fence exists to prevent, so a broken registry never quietly downgrades a tool to “trusted”. The one exception is “no registry at all” (e.g. a slim build): the hardcoded external list is the whole answer there, so unknown tools stay trusted — otherwise every ordinary function tool would be fenced.

Situation	Result
Tool is in the hardcoded external list	External — result is fenced
Registry exists and says `EXTERNAL`	External — result is fenced
Registry exists and says `TRUSTED` (or `None`)	Trusted — result passes through
Registry exists and raises while answering	External — result is fenced (fail closed)
No registry available at all	Trusted (fallback to hardcoded list only)

Fixed in PR #4969.

The hook-level scanner does not read a trust label off the payload. Prompt strings passed through before_llm_call are scanned unconditionally so a forged _source field cannot bypass the checks. Tool-level trust (external vs internal tool) is still governed by how the tool is registered — that hasn’t changed.

Configuration Options

Option	Type	Default	Description
`trust_level`	`"trusted"` \| `"external"`	`"trusted"`	Set on `register_tool(..., trust_level="external")`
`MIN_CONTENT_LENGTH_FOR_WRAPPING`	`int`	`32`	Minimum string length before wrapping
Registry lookup error	—	—	Treated as external (fail closed)

Programmatic Injection Defense

The auto-wrap above protects tool outputs. To also scan all agent prompts at the hook layer, enable the injection-defense pipeline:

from praisonai.security import enable_injection_defense

hook_ids = enable_injection_defense()

This registers hooks on BEFORE_TOOL and BEFORE_AGENT that scan inputs through a 6-check pipeline and block critical threats.

enable_injection_defense() registers on the process-global praisonaiagents.hooks registry — the policy applies to every Agent in the process. In a multi-tenant host (e.g. praisonai serve) do not rely on it for per-tenant isolation. To scope or tear down later, keep the returned hook_ids and remove them via praisonaiagents.hooks.remove_hook:

from praisonaiagents.hooks import remove_hook

for hid in hook_ids.values():
    remove_hook(hid)

One-liner (both defenses)

from praisonai.security import enable_security

hook_ids = enable_security()  # injection defense + audit log

enable_security() is the same story: it registers process-global hooks. One tenant’s extra_patterns would apply to every tenant sharing the process. Use per-request add_hook in multi-tenant hosts, or hold the returned hook IDs and remove them at teardown.

Best Practices

Mark external data sources as external

Web APIs, scraping, MCP servers you do not control, and third-party feeds should use trust_level="external".

Do not strip safety markers

Removing <external_tool_result> tags breaks the model’s boundary between data and instructions.

Prefer external when unsure

Wrapping cost is minimal; under-marking exposes you to injection.

Layer with other guards

Combine with Tool Circuit Breaker and input validation for defence in depth.

Scope hooks in multi-tenant hosts

The hook registry is process-global. In multi-tenant servers, hold the returned hook IDs and remove them via praisonaiagents.hooks.remove_hook on teardown, or add per-request hooks manually instead of using the enable_* one-liner.

Related defence. Tool outputs get wrapped in <external_tool_result> markers (this page). Inbound webhook and hook payloads get the ingress counterpart — wrapped in <external_request_payload>, described in Untrusted Request Fencing. Platform display names and group titles interpolated into the [{sender}] attribution prefix get a different treatment — collapse-and-strip — described in Sender Attribution Sanitisation.

Inter-Agent Provenance

The agent↔agent counterpart — sub-agent output labelled as data

Untrusted Request Fencing

The ingress counterpart — webhook and hook payloads fenced as data

Attribution Sanitisation

Neutralise untrusted platform display names in the prompt prefix

Tool Circuit Breaker

Automatic tool failure detection and recovery

Security Overview

Complete security features and best practices

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Prompt Injection Protection

Quick Start

How It Works

What happens if the trust decision fails

Configuration Options

Programmatic Injection Defense

One-liner (both defenses)

Best Practices

Inter-Agent Provenance

Untrusted Request Fencing

Attribution Sanitisation

Tool Circuit Breaker

Security Overview

​Quick Start

​How It Works

​What happens if the trust decision fails

​Configuration Options

​Programmatic Injection Defense

​One-liner (both defenses)

​Best Practices

​Related

Inter-Agent Provenance

Untrusted Request Fencing

Attribution Sanitisation

Tool Circuit Breaker

Security Overview

Quick Start

How It Works

What happens if the trust decision fails

Configuration Options

Programmatic Injection Defense

One-liner (both defenses)

Best Practices

Related