🔍 Agent Polis

Impact Preview for AI Agents - "Terraform plan" for autonomous AI actions

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.11+](https://www.python.org/downloads/)

See exactly what will change before any AI agent action executes.

Agent Polis intercepts proposed actions from autonomous AI agents, analyzes their impact, shows you a diff preview of what will change, and only executes after human approval. Stop worrying about your AI agent deleting your production database.

🎯 The Problem

Autonomous AI agents are powerful but dangerous. Recent incidents:

Replit Agent deleted a production database, then lied about it
Cursor YOLO mode deleted an entire system including itself
Claude Code learned to bypass safety restrictions via shell scripts

Developers want to use AI agents but don't trust them. Current solutions show what agents want to do, not what will happen. There's no "terraform plan" equivalent for AI agent actions.

🚀 The Solution

AI Agent proposes action → Agent Polis analyzes impact → Human reviews diff → Approve/Reject → Execute

# Example: Agent wants to write to config.yaml
- database_url: postgresql://localhost:5432/dev
+ database_url: postgresql://prod-server:5432/production
! WARNING: Production database URL detected (CRITICAL RISK)

✨ Features

Impact Preview: See file diffs, risk assessment, and warnings before execution
Approval Workflow: Approve, reject, or modify proposed actions
Risk Assessment: Automatic detection of high-risk operations (production data, system files, etc.)
Audit Trail: Event-sourced log of every proposed and executed action
SDK Integration: Easy @require_approval decorator for your agent code
Dashboard: Streamlit UI for reviewing and approving actions

🚀 Quick Start (2 minutes)

The fastest way to try Agent Polis is the MCP server with Claude Desktop or Cursor.

1. Install & Run

pip install impact-preview
impact-preview-mcp

2. Configure Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
    "mcpServers": {
        "impact-preview": {
            "url": "http://localhost:8000/mcp"
        }
    }
}

3. Try It

Ask Claude to edit a file - it now has these tools:

| Tool | What it does | |------|--------------| | preview_file_write | Shows diff before any edit | | preview_file_delete | Shows what will be lost | | preview_shell_command | Flags dangerous commands | | check_path_risk | Quick risk check for any path |

Example prompt: > "Preview what would happen if you changed the database URL in config.yaml to point to production"

Claude will show you the diff and risk assessment before making changes.

---

📦 Full Server Installation

For the complete approval workflow with dashboard and API:

# Using Docker (recommended)
docker-compose up -d

# Or locally
pip install impact-preview
impact-preview

Register an Agent

curl -X POST http://localhost:8000/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My AI coding assistant"}'

Submit Action → Review → Approve

# Submit
curl -X POST http://localhost:8000/api/v1/actions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "file_write", "target": "/app/config.yaml", "description": "Update DB URL", "payload": {"content": "db: prod"}}'

# Preview
curl http://localhost:8000/api/v1/actions/ACTION_ID/preview -H "X-API-Key: YOUR_API_KEY"

# Approve (or reject)
curl -X POST http://localhost:8000/api/v1/actions/ACTION_ID/approve -H "X-API-Key: YOUR_API_KEY"

Audit Trail (Events)

You can retrieve the complete audit trail for an action:

curl http://localhost:8000/api/v1/actions/ACTION_ID/events -H "X-API-Key: YOUR_API_KEY"

ActionPreviewGenerated event payload includes machine-readable governance context:

data.governance.policy.decision / data.governance.policy.matched_rule_id
data.governance.scanner.reason_ids / data.governance.scanner.max_severity

---

🐍 SDK Integration

Wrap your agent's dangerous operations:

from agent_polis import AgentPolisClient

client = AgentPolisClient(api_url="http://localhost:8000", api_key="YOUR_KEY")

# Decorator approach - blocks until human approves
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
    with open(path, 'w') as f:
        f.write(content)

# This will: submit → wait for approval → execute only if approved
write_config("/etc/myapp/config.yaml", "new content")

🖥️ Dashboard

Launch the Streamlit dashboard to review pending actions:

pip install impact-preview[ui]
streamlit run src/agent_polis/ui/app.py

📚 API Reference

Actions API

| Endpoint | Method | Description | |----------|--------|-------------| | /api/v1/actions | POST | Submit action for approval | | /api/v1/actions | GET | List your actions | | /api/v1/actions/pending | GET | List pending approvals | | /api/v1/actions/{id} | GET | Get action details | | /api/v1/actions/{id}/preview | GET | Get impact preview | | /api/v1/actions/{id}/diff | GET | Get diff output | | /api/v1/actions/{id}/approve | POST | Approve action | | /api/v1/actions/{id}/reject | POST | Reject action | | /api/v1/actions/{id}/execute | POST | Execute approved action |

Action Types

file_write - Write content to a file
file_create - Create a new file
file_delete - Delete a file
file_move - Move/rename a file
db_query - Execute a database query (read)
db_execute - Execute a database statement (write)
api_call - Make an HTTP request
shell_command - Run a shell command
custom - Custom action type

Risk Levels

Low: Read operations, safe changes
Medium: Write operations to non-critical files
High: Delete operations, system files
Critical: Production data, irreversible changes

🔧 Configuration

# .env
SECRET_KEY=your-secret-key
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agent_polis
REDIS_URL=redis://localhost:6379/0

# Optional
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO

🗺️ Roadmap

| Version | Focus | Status | |---------|-------|--------| | v0.2.0 | File operation preview | Current | | v0.3.0 | Database operation preview | Planned | | v0.4.0 | API call preview | Planned | | v0.5.0 | IDE integrations (Cursor, VS Code) | Planned | | v1.0.0 | Production ready | Planned |

🤝 Contributing

git clone https://github.com/agent-polis/impact-preview.git
cd impact-preview
pip install -e .[dev]
pre-commit install
pytest

📄 License

MIT License - see LICENSE for details.

---

Built for developers who want AI agents they can actually trust.

impact-preview