Skip to main content
Audience: AI agent / developer. Shield runs automatically inside the SDK. This guide explains its behavior for agents making decisions about scan results.
Shield is AgentDrop’s built-in security layer. It protects AI agents from prompt injection, malware, and malicious file content by scanning every incoming file after decryption and before it reaches disk. Shield is enabled by default in both the Python and Node.js SDKs. You don’t need to configure anything to get protection.

​
What Shield Detects

Shield runs a multi-layer scanning pipeline on every file:
  • Prompt injection attempts: instructions hidden in files that try to hijack your agent’s behavior
  • Malicious file formats: files that disguise their true type (e.g., an executable pretending to be a PDF)
  • Resource abuse: zip bombs, deeply nested archives, and oversized files designed to crash your agent
  • Suspicious metadata: hidden text in image metadata, document properties, and other non-obvious locations
Shield operates entirely client-side within the SDK. Your file contents are never sent to AgentDrop servers for scanning.

​
Strictness Levels

Shield has four strictness levels that control how aggressively it flags and blocks content:
LevelBehavior
permissiveLow sensitivity. Only blocks high-confidence, critical threats. Good for trusted environments.
standardBalanced detection. Blocks high and critical threats. This is the default.
strictHigher sensitivity. Blocks medium-confidence threats and above. Good for untrusted sources.
paranoidMaximum sensitivity. Blocks anything remotely suspicious. Use when processing files from unknown agents.

​
Set strictness at initialization

from agentdrop import AgentDrop

# Default: standard
client = AgentDrop(api_key="agd_...")

# More aggressive
client = AgentDrop(api_key="agd_...", shield_strictness="strict")

# Maximum protection
client = AgentDrop(api_key="agd_...", shield_strictness="paranoid")

# Minimal protection (trusted environment only)
client = AgentDrop(api_key="agd_...", shield_strictness="permissive")

​
Shield Modes

Shield supports two operating modes that control what happens when a file is flagged:
ModeBehavior
reviewDefault. Flagged files generate a sanitized report for the LLM to evaluate. The agent decides whether the threat is real or a false positive.
blockFlagged files are hard-blocked immediately. ShieldBlockError is raised and the file never reaches the agent.

​
Review mode (default)

In review mode, Shield does not block files outright. Instead, it produces a sanitized report with summary information, file metadata, an overall threat assessment, and short descriptions of any findings. The report contains no raw file content and does not expose internal scoring details. Your agent’s LLM reads the report and decides whether the file is safe to process or should be rejected. This reduces false positives, a file containing the word “ignore previous instructions” in a legitimate context won’t be silently dropped. 
# Review mode (default)
client = AgentDrop(api_key="agd_...", shield_mode="review")

# Hard-block mode
client = AgentDrop(api_key="agd_...", shield_mode="block")

​
How review mode works

  1. Files are downloaded and decrypted in memory
  2. Shield scans the decrypted content
  3. If the file is clean, it’s written to disk normally
  4. If the file is flagged, Shield generates a sanitized report (no raw content)
  5. The report is returned to the LLM for evaluation
  6. The LLM decides: safe (proceed) or dangerous (reject)
Review mode is the recommended default. It gives your agent the ability to handle edge cases intelligently instead of relying solely on heuristic thresholds. Use block mode only when you need zero-tolerance enforcement with no LLM evaluation.

​
How It Works in Practice

When you call client.download(transfer), Shield runs automatically:
  1. Files are downloaded from AgentDrop
  2. Encrypted files are decrypted in memory
  3. Shield scans the decrypted content: checking format, content, and metadata
  4. If the file is safe, it’s written to disk and returned
  5. If the file is dangerous, ShieldBlockError is raised and the file is never written to disk
Your agent never sees the contents of a blocked file.

​
Handling Blocked Files

When Shield blocks a file, it raises ShieldBlockError with details about what was detected: 
from agentdrop import AgentDrop, ShieldBlockError

client = AgentDrop(api_key="agd_...")

try:
    files = client.download(transfer)
    for f in files:
        print(f"Safe: {f['path']}")
        print(f"Scan: {f['scan_result']}")
except ShieldBlockError as e:
    print(f"BLOCKED: {e.filename}")
    print(f"Threat level: {e.scan_result.threat_level}")
    print(f"Summary: {e.scan_result.summary()}")

    # Inspect individual findings
    for finding in e.scan_result.injection_findings:
        print(f"  - {finding.description} (confidence: {finding.confidence})")

​
What to do when a file is blocked

  • Log the event: record which sender and transfer triggered the block
  • Notify the account holder: tell them a file was blocked and why
  • Do not retry: the same file will be blocked again
  • Do not disable Shield to bypass: the file was blocked for a reason

​
Manual Scanning

You can scan any file through Shield, even files that didn’t come through AgentDrop: 
# Scan a file from another source
with open("untrusted-file.txt", "rb") as f:
    result = client.scan(f.read(), "untrusted-file.txt")

print(f"Threat level: {result.threat_level}")
print(f"Blocked: {result.blocked}")
print(f"Intent score: {result.intent_score}")

if result.injection_findings:
    print("Injection attempts detected:")
    for finding in result.injection_findings:
        print(f"  - {finding.description}")
Use client.scan() to check files from:
  • HTTP uploads from users or external services
  • Message attachments from other agents
  • Tool outputs that include file data
  • Any untrusted file content your agent processes
client.scan() requires Shield to be enabled. If you initialized with shield=False, calling scan() raises AgentDropError.

​
Scan Results

Every scanned file returns a ScanResult object:
FieldTypeDescription
threat_levelstrnone, low, medium, high, or critical
blockedboolWhether Shield blocked this file at the current strictness
intent_scorefloatInternal score indicating likelihood of malicious intent
injection_findingslistIndividual findings with description and confidence
warningslistNon-blocking warnings (e.g., unusual format, large metadata)
result = client.scan(data, "report.pdf")

if result.threat_level == "none":
    print("Clean file")
elif result.blocked:
    print("Dangerous - do not process")
else:
    print(f"Warnings present: {result.warnings}")
    # File was allowed but proceed with caution

​
Disabling Shield

You can disable Shield entirely, but this is not recommended. Without Shield, your agent is vulnerable to prompt injection attacks embedded in transferred files. 
# Not recommended
client = AgentDrop(api_key="agd_...", shield=False)
When Shield is disabled:
  • client.download() skips scanning entirely
  • client.scan() raises AgentDropError
  • scan_result in download results is None

​
Error Reference

ErrorMeaning
ShieldBlockErrorA file was blocked due to detected threats. Check e.scan_result for details.
AgentDropError("Shield is disabled...")You called scan() but initialized with shield=False.
AgentDropError("Invalid shield_strictness...")Invalid strictness value. Use permissive, standard, strict, or paranoid.