Impact Preview

🚀 エージェントポリス (Agent Polis)

AIエージェントの影響予測ツール - 自律的なAIアクションの「Terraform plan」

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

エージェントポリスは、自律的なAIエージェントが提案するアクションを傍受し、その影響を分析し、何が変更されるかの差分プレビューを表示します。人間の承認を得た後にのみ実行します。AIエージェントが本番データベースを削除する心配をなくしましょう。

🚀 クイックスタート

エージェントポリスを試す最速の方法は、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にファイルを編集するように依頼すると、以下のツールが使用可能になります。

サンプルプロンプト:

"config.yamlのデータベースURLを本番環境に変更した場合の影響をプレビューして"

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

✨ 主な機能

• 影響予測: 実行前にファイルの差分、リスク評価、警告を表示します。
• 承認ワークフロー: 提案されたアクションを承認、拒否、または修正できます。
• リスク評価: 高リスクの操作（本番データ、システムファイルなど）を自動検出します。
• 監査トレイル: 提案されたすべてのアクションと実行されたアクションのイベントソーシングログを記録します。
• SDK統合: エージェントコードに簡単に@require_approvalデコレータを使用できます。
• ダッシュボード: アクションのレビューと承認を行うためのStreamlit UIが用意されています。

📦 インストール

完全な承認ワークフローとダッシュボード、APIを使用するには、以下の手順でインストールします。

# Dockerを使用する場合（推奨）
docker-compose up -d

# またはローカルでインストール
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"}'

アクションの送信 → レビュー → 承認

# アクションの送信
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"}}'

# プレビューの取得
curl http://localhost:8000/api/v1/actions/ACTION_ID/preview -H "X-API-Key: YOUR_API_KEY"

# 承認（または拒否）
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

💻 使用例

基本的な使用法

from agent_polis import AgentPolisClient

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

# デコレータアプローチ - 人間が承認するまでブロック
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
    with open(path, 'w') as f:
        f.write(content)

# これは以下の処理を行います: 送信 → 承認を待つ → 承認された場合のみ実行
write_config("/etc/myapp/config.yaml", "new content")

高度な使用法

# ダッシュボードの起動
pip install impact-preview[ui]
streamlit run src/agent_polis/ui/app.py

📚 ドキュメント

アクションAPI

アクションタイプ

• 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

# オプション
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO

ロードマップ

貢献方法

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

📄 ライセンス

MITライセンス - 詳細はLICENSEを参照してください。

信頼できるAIエージェントを求める開発者のために構築されました。