agentic-compute

🏆 Track 01 ハッカソンの評価基準への対応

このプロジェクトは、AI エージェント向けストアフロントに関する Razorpay Track 01 の要件に厳密に準拠しています。

🔒 ゲート制御（エンドツーエンドで取引可能）：

AI エージェントには API 呼び出しごとに課金されます。ウォレットの残高が空の場合、FastAPI ミドルウェアがリクエストを捕捉し、適切な 402 Payment Required を返します。残高がある場合は、暗号資産トークンを検証し、Base ネットワーク経由で USDC を決済します。

⏱️ 制限付き（リソースの枯渇ゼロ）：

すべてのサンドボックスは Azure Container Apps Dynamic Sessions 内で実行されます。コード実行は、Pydantic モデルによって適用される最大 15 秒のタイムアウトに厳密に制限されています。メモリを枯渇させる悪意のあるスクリプトは即座に終了されます。

📊 説明可能（監査証跡）：

成功した取引も失敗した取引もすべて、正確な price_usdc、duration_ms、実行終了コードを記録した不変の AUDIT_RECORD をローカルに生成します。

🏗️ アーキテクチャとファイル構成

graph TD
    A[Claude Desktop App<br>Agent Client] -->|Tool Invocation| B{FastAPI x402 Middleware}
    
    subgraph Gate ["The Payment Gate"]
        B -->|Funded Wallet| D[Settle USDC via Base Network]
        B -->|Empty Wallet| C[HTTP 402 Payment Required<br>Graceful Failure]
        D -.->|Log| Z[(Local Audit Trail)]
        C -.->|Log| Z
    end
    
    %% Invisible structural link to force vertical placement
    Z ~~~ E
    
    D --> E[Azure Container Apps<br>Dynamic Session Pool]
    C -.->|Agent Retries| A
    
    subgraph Cloud ["Bounded Cloud Execution"]
        E --> F[15s Python Execution Timeout]
        F --> G[Generate Text / Base64 Image]
    end
    
    G -->|Stream Payload| H[mcp_client.py]
    
    subgraph Local ["Local System (Zero-Context Rendering)"]
        H -->|JSON Response| A
        H -->|Image Payload| I[(Save to Local PNG)]
    end
    
    classDef gate fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef success fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    class C gate;
    class D success;

agentic-compute-mcp/
├── README.md                      # Documentation & Setup
├── .env.example                   # Environment variable template
├── main.py                        # The Backend: FastAPI, x402 Gate, and Azure routing
├── mcp_client.py                  # The Bridge: Claude Desktop tool definitions
├── sandbox.py                     # Core Azure Dynamic Sessions execution logic
├── pyproject.toml                 # Python package and dependency configurations
├── requirements.txt               # Dependencies (FastAPI, azure-identity, uvicorn, etc.)
├── server.json                    # MCP server configuration details
├── glama.json                     # Glama registry metadata for the AI agent storefront
└── llms.txt                       # Context file for LLM integration

🖼️ 機能のハイライト：コンテキストを介さない画像レンダリング

LLM のコンテキストウィンドウで base64 画像文字列を扱うのは非常に不安定で、数千トークンを消費します。agentic-compute-mcp はこの処理をローカルで行います。

Claude が generate_plot を呼び出すと、Azure サンドボックスがグラフを生成し、ペイロードを MCP クライアントにストリーミングします。クライアントはペイロードを自動的に捕捉してデコードし、最適化された_load_trend.png としてローカルマシンに直接保存します。これにより、トークンの枯渇を防ぐために LLM のコンテキストウィンドウを完全に迂回します。

🌙 開発者メモ：午前2時の出来事と適切なエラー処理

適切なエラー処理： エージェント間のコマースに関する Track 01 の要件を満たすため、バックエンドは適切にエラーを処理するよう設計されています。エージェントが資金なしでコードを実行しようとすると、FastAPI ミドルウェアがペイロードを捕捉し、明確な 402 Payment Required エラーを返します。これにより、コンピュートリソースの不正利用を防ぎ、エージェントが /verify および /settle エンドポイントへ自動的にルートを切り替えられるようになります。

午前2時のデバッグ： 悪意のあるリソース枯渇を防ぐため、Pydantic による厳格な 5 秒の実行上限を設けました。しかし午前2時、簡単な Python テストスクリプトが何度もタイムアウトしました。セキュリティを確保するために、Azure Dynamic Sessions がリクエストごとに 100％新しく、分離されたマイクロ VM をプロビジョニングするため、コールドスタートに 8 秒かかることが分かりました。そこで MCP クライアント側の制限を 15 秒に引き上げると、サンドボックスが起動してコードを実行し、ちょうど 5.7 秒で結果を返せるようになりました。これにより、クラウドインフラを圧迫することなく、設定した制限が機能することを確認できました。

⚙️ インストールとセットアップ

2 つのコンポーネントを実行する必要があります。バックエンドサーバーと MCP クライアントです。

1. バックエンドサーバー（main.py）のセットアップ バックエンドは x402 の決済ゲートを処理し、コードを Azure にルーティングします。

依存関係をインストールします：

pip install -r requirements.txt

.env.example を基に .env ファイルを作成し、設定を追加します。

コードスニペット：

AZURE_POOL_ENDPOINT="https://<YOUR-POOL-NAME>.azurecontainerapps.io"
MY_WALLET_ADDRESS="0xYourActualWalletAddress"

FastAPI サーバーをローカルで実行します：

uvicorn main:app --host 127.0.0.1 --port 8000 --reload

2. MCP クライアント（mcp_client.py）のセットアップ Claude Desktop にこのサーバーをインストールするには、次の内容を claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "agentic-compute": {
      "command": "python",
      "args": ["/path/to/your/repo/mcp_client.py"],
      "env": {
        "EVM_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

注：パスを置き換え、Claude が x402 の少額取引を処理できるよう、資金を入金した EVM ウォレットキーを指定してください。

🧰 利用可能な MCP ツール

このサーバーは、以下のエンドポイントを公開します。エージェントは呼び出す前に、必要な機能とコストを評価する必要があります。

ツール	コスト（USDC）	入力	出力	使用する場面
execute_code	0.10	有効な Python スクリプト文字列。	テキスト（stdout/stderr）。返却上限は 8KB です。	隔離された Azure サンドボックスで、任意の Python ロジック、負荷の高い計算、またはデータの並べ替えを実行します。ローカル FS 操作には使用しないでください。
sanitize_csv	0.25	未加工の未整形 CSV 文字列。	JSON 配列。	null 値を処理し（NaN を null に変換）、ヘッダーを正規化して、モデリングの前に空の行を削除します。
optimize_ga	0.50	数値データの JSON 配列。	最適化されたモデルパラメーターと MAPE スコア。	負荷予測、予測モデリング、または曲線フィッティングに使用します。比例変異を採用し、MAPE 精度 1% 未満を実現します。
generate_plot	0.30	座標とグラフ設定の JSON 配列。	成功文字列（ファイルはローカルに保存されます）。	トークン生成の上限に達したり、ローカル GUI 依存関係が必要になったりすることなく、データを可視化します。

🤖 システムプロンプトの指示（開発者向け）

エージェントによる自律的なツール利用を有効にするには、このスニペットをエージェントのシステムプロンプトまたは .cursorrules ファイルにコピーして貼り付けてください。

You are equipped with the `agentic-compute-mcp` backend. Use these tools for heavy computation or secure data execution. 
- You must pay for invocations automatically using the configured x402 EVM private key.
- Do NOT attempt to run Python locally if data requires complex optimization; route it to `execute_code`.
- For any unformatted CSV data, run `sanitize_csv` before performing mathematical analysis.
- When generating charts, use `generate_plot`. The backend will automatically save the chart directly to the local file system as a PNG. Do not attempt to read base64 strings.

ライセンス

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