agent-preflight
Preview what your AI agent will do before it does it.
The terraform plan for AI agents. Open-source middleware that intercepts tool calls, classifies risk, and shows a human-readable execution plan before anything touches the real world.
================================================================
PREFLIGHT PLAN 5 action(s)
Send Q3 report to Sarah at Acme
================================================================
WARNING: 3 irreversible action(s) in plan
1. search_contacts [READ] [REVERSIBLE]
query: 'Sarah from Acme'
!! 2. send_email [WRITE] [IRREVERSIBLE]
to: 'sarah@acme.com'
subject: 'Q3 Performance Report'
body: 'Hi Sarah, please find the Q3 report attached...'
> External communication - cannot be unsent
! 3. update_database [WRITE] [REVERSIBLE]
query: "UPDATE invoices SET status='sent' WHERE quarter=...
!! 4. delete_old_records [DELETE] [IRREVERSIBLE]
table: 'temp_reports'
before_date: '2025-01-01'
> Destructive operation
! 5. generate_image [EXEC] [IRREVERSIBLE]
prompt: 'Professional header image for Q3 report'
est. cost: $0.0800
================================================================
Risk: HIGH (3 irreversible)
Cost: $0.0800 estimated
Actions: 5 total
================================================================
Why
Agents take irreversible actions with zero preview:
- $47K burned by a recursive agent loop that ran 11 days unnoticed
- Production databases deleted by coding agents despite freeze instructions
- $2.3M in fraudulent wire transfers approved by AI assistants
- 1,184 malicious agent skills found on package registries
Every incident had the same root cause: nobody saw what the agent was about to do.
Observability tools watch after. Security tools block. Preflight shows you the plan.
Install
pip install agent-preflight
Quick Start
from agent_preflight import Preflight
pf = Preflight()
# Wrap your agent's tools
@pf.intercept
def send_email(to, subject, body):
smtp.send(to, subject, body)
@pf.intercept
def update_database(query):
db.execute(query)
@pf.intercept(cost=0.08)
def generate_image(prompt):
return dalle.generate(prompt)
# Run your agent in dry-run mode
plan = pf.dry_run(my_agent_workflow, task="Send Q3 report")
# See the full plan before anything executes
print(pf.format(plan))
# Approve and execute
plan.approve()
plan.execute()
Features
Action Classification - Automatically detects risk level, reversibility, and action type from function names and arguments. send_email -> IRREVERSIBLE. get_users -> READ/LOW. DROP TABLE in args -> CRITICAL.
Loop Detection - Flags when the same tool is called 3+ times, catching runaway agent loops before they become $47K bills.
Cost Tracking - Attach cost estimates to tools, set budget limits. Preflight warns when a plan exceeds your threshold.
SQL Danger Detection - Catches DROP TABLE, DELETE without WHERE, TRUNCATE, and other destructive SQL patterns in arguments.
Approve/Execute Flow - Plans must be explicitly approved before execution. No accidental runs.
JSON Export - plan.to_json() for programmatic use, CI/CD integration, and audit trails.
Context Manager - Record mode for capturing actions in existing code:
with pf.recording(task="nightly cleanup") as rec:
cleanup_old_files()
archive_logs()
print(pf.format(rec.plan))
Custom Classifiers - Add your own classification logic:
def my_classifier(action):
if "prod" in str(action.args):
action.risk_level = RiskLevel.CRITICAL
action.risk_reasons.append("Production environment detected")
return action
pf.add_classifier(my_classifier)
How It Works
- Intercept -
@pf.interceptwraps your tool functions - Dry Run -
pf.dry_run()executes your agent logic but captures calls instead of running them - Classify - Each captured action is analyzed for risk, reversibility, and type
- Render - Human-readable plan with color-coded risk levels
- Approve - Explicit approval gate before any real execution
- Execute - Replays captured calls against real functions
Zero dependencies. Works with any Python agent framework.
Demo
preflight demo
API
Preflight(auto_classify=True, max_actions=100, cost_limit=None)
Create a preflight engine.
auto_classify- Run built-in classifiers on captured actionsmax_actions- Safety cap on captured actions per dry runcost_limit- Warn if total estimated cost exceeds this
@pf.intercept / @pf.intercept(cost=0.05, reversible=False)
Decorator to register a tool for interception. Supports manual metadata overrides.
pf.dry_run(run_fn, task="")
Execute run_fn in dry-run mode. All intercepted calls are captured, not executed. Returns a Plan.
Plan
plan.actions- List of capturedActionCaptureobjectsplan.overall_risk- Highest risk level across all actionsplan.irreversible_count- Number of irreversible actionsplan.warnings- Auto-generated warnings (loops, cost, irreversible actions)plan.approve()- Mark plan as approvedplan.execute()- Execute all actions (must approve first)plan.to_json()- Export as JSONplan.to_dict()- Export as dict
pf.format(plan, color=True)
Render plan as terminal output with ANSI colors.
Roadmap
- LangChain/LangGraph callback adapter
- MCP tool wrapper
- Drift detection (compare plans over time)
- GitHub Action for CI/CD
- Web dashboard
License
MIT
Metadata
Release files for agent-preflight 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_preflight-0.1.0.tar.gz | 14.0 kB | Without provenance | Details for agent_preflight-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_preflight-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_preflight-0.1.0-py3-none-any.whl |
Total release size: 27.4 kB
Release files / agent_preflight-0.1.0.tar.gz
| Download URL | agent_preflight-0.1.0.tar.gz |
|---|---|
| Size | 14.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
817fa3ec0ba625e51888dd3622e20234c535050cdc259949f99d30e062ec9d14
|
|
BLAKE2b-256 checksum How to use checksums |
911b40224fe30c1c1c2d63dd0e2f9bbef7373e8a8c454773873f4209da616d7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.2
|
Release files / agent_preflight-0.1.0-py3-none-any.whl
| Download URL | agent_preflight-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ee2005038e2046c4e83ac48d88799f98cfd32c9cb944c2012dfab375e4ed7f89
|
|
BLAKE2b-256 checksum How to use checksums |
937e750f1cf2503bacb933a5c4edf6079412c04e5231c67910d97a716b9dded5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.0.0 CPython/3.12.2
|
Security for agent-preflight 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.