impact-preview

🔍 Agent Polis

AI エージェントの影響プレビュー ― 自律型 AI アクションのための「Terraform plan」

AI エージェントのアクションが実行される前に、何が変わるかを正確に確認できます。

Agent Polis は、自律型 AI エージェントが提案したアクションを傍受してその影響を分析し、何が変わるかの差分プレビューを表示します。人間の承認後にのみ実行されます。AI エージェントが本番データベースを削除するのではないかと心配する必要はありません。

🎯 問題

自律型 AI エージェントは強力ですが、危険でもあります。最近の事例：

• Replit Agent が本番データベースを削除し、その後それについて嘘をついた
• Cursor YOLO mode が自分自身を含むシステム全体を削除した
• Claude Code がシェルスクリプトを使って安全制限を回避する方法を学習した

開発者は AI エージェントを使いたいと思っていますが、信頼できずにいます。現在のソリューションが示すのは、エージェントが「何をしようとしているか」であり、「実際に何が起きるか」ではありません。AI エージェントのアクションには、「terraform plan」に相当するものがありません。

🚀 ソリューション

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)

✨ 機能

• 影響プレビュー：実行前にファイルの差分、リスク評価、警告を確認できます
• 承認ワークフロー：提案されたアクションを承認、却下、または変更できます
• リスク評価：リスクの高い操作（本番データ、システムファイルなど）を自動検出します
• 監査証跡：提案および実行されたすべてのアクションをイベントソーシング形式で記録します
• SDK 統合：エージェントのコードに簡単に追加できる @require_approval デコレーター
• ダッシュボード：アクションを確認して承認するための Streamlit UI

🚀 クイックスタート（2 分）

Agent Polis を最も手早く試すには、Claude Desktop または Cursor と MCP サーバーを使用します。

1. インストールと起動

pip install impact-preview
impact-preview-mcp

2. Claude Desktop の設定

設定に追加します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）：

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

3. 試してみる

Claude にファイルの編集を依頼すると、次のツールが使えるようになります。

ツール	機能
preview_file_write	編集前に差分を表示します
preview_file_delete	削除すると失われる内容を表示します
preview_shell_command	危険なコマンドにフラグを付けます
check_path_risk	任意のパスのリスクをすばやく確認します

プロンプトの例：

「config.yaml のデータベース URL を本番環境に向けて変更した場合に何が起きるか、プレビューしてください」

Claude は変更を行う前に、差分とリスク評価を表示します。

---

📦 サーバーの完全インストール

ダッシュボードと API を含む完全な承認ワークフローを利用する場合：

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

# Or locally
pip install impact-preview
impact-preview

エージェントの登録

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
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"

監査証跡（イベント）

アクションの完全な監査証跡を取得できます。

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

ActionPreviewGenerated イベントのペイロードには、機械可読なガバナンスコンテキストが含まれます。

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

---

🐍 SDK 統合

エージェントの危険な操作をラップします。

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")

🖥️ ダッシュボード

保留中のアクションを確認するには、Streamlit ダッシュボードを起動します。

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

📚 API リファレンス

アクション API

エンドポイント	メソッド	説明
/api/v1/actions	POST	承認を求めてアクションを送信します
/api/v1/actions	GET	自分のアクションを一覧表示します
/api/v1/actions/pending	GET	保留中の承認を一覧表示します
/api/v1/actions/{id}	GET	アクションの詳細を取得します
/api/v1/actions/{id}/preview	GET	影響プレビューを取得します
/api/v1/actions/{id}/diff	GET	差分出力を取得します
/api/v1/actions/{id}/approve	POST	アクションを承認します
/api/v1/actions/{id}/reject	POST	アクションを却下します
/api/v1/actions/{id}/execute	POST	承認済みアクションを実行します

アクションの種類

• file_write - ファイルにコンテンツを書き込みます
• file_create - 新しいファイルを作成します
• file_delete - ファイルを削除します
• file_move - ファイルを移動／名前変更します
• db_query - データベースクエリを実行します（読み取り）
• db_execute - データベースステートメントを実行します（書き込み）
• api_call - HTTP リクエストを送信します
• shell_command - シェルコマンドを実行します
• custom - カスタムアクションの種類

リスクレベル

• 低：読み取り操作、安全な変更
• 中：重要度の低いファイルへの書き込み操作
• 高：削除操作、システムファイル
• 重大：本番データ、取り消し不能な変更

🔧 設定

# .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

🗺️ ロードマップ

バージョン	注力項目	状況
v0.2.0	ファイル操作のプレビュー	現在
v0.3.0	データベース操作のプレビュー	予定
v0.4.0	API 呼び出しのプレビュー	予定
v0.5.0	IDE 連携（Cursor、VS Code）	予定
v1.0.0	本番利用可能な状態	予定

🤝 貢献

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

📄 ライセンス

MIT License - 詳細は LICENSE を参照してください。

---

AI エージェントを本当に信頼したい開発者のために作られました。