agentic-compute

🏆 已满足 Track 01 黑客松标准

本项目严格遵循 Razorpay Track 01 对 AI Agent 商店的要求：

🔒 有门槛（端到端可交易）：

AI Agent 按 API 调用次数付费。如果钱包余额不足，FastAPI 中间件会拦截请求，并返回友好的 402 Payment Required 错误。如果资金充足，则会验证加密货币代币，并通过 Base 网络结算 USDC。

⏱️ 有边界（零资源耗尽）：

所有沙箱都在 Azure Container Apps Dynamic Sessions 中运行。代码执行被严格限制在最长 15 秒的超时范围内，并由 Pydantic 模型强制执行。恶意的内存占用脚本会立即被终止。

📊 可解释（审计跟踪）：

每笔成功和失败的交易都会在本地生成一条不可变的 AUDIT_RECORD，详细记录确切的 price_usdc、duration_ms 和执行退出代码。

🏗️ 架构与文件结构

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

🖼️ 功能亮点：零上下文图像渲染

在大模型上下文窗口中处理 Base64 图像字符串一向不可靠，还会消耗数千个 Token。agentic-compute-mcp 在本地解决了这个问题。

Claude 调用 generate_plot 时，Azure 沙箱会生成图表，并将载荷流式传回 MCP 客户端。客户端会自动拦截载荷、解码，并将其直接保存到本地计算机，文件名为 optimized_load_trend.png——完全绕过大模型上下文窗口，避免 Token 耗尽。

🌙 开发者说明：凌晨 2 点的故事与优雅失败

优雅失败： 为满足 Track 01 对 Agent 间交易的要求，后端经过设计，可在失败时优雅处理。如果 Agent 尝试在没有资金的情况下执行代码，FastAPI 中间件会拦截载荷，并返回清晰的 402 Payment Required 错误。这可以防止算力被盗用，并允许 Agent 自动转到 /verify 和 /settle 端点。

凌晨 2 点的调试： 我们设置了严格的 5 秒 Pydantic 执行限制，以防止恶意耗尽资源。但凌晨 2 点时，我们简单的 Python 测试脚本却总是超时。我们意识到，为了确保安全，Azure Dynamic Sessions 会为每个请求配置一台全新、隔离的微型虚拟机，导致冷启动延迟达 8 秒。将 MCP 客户端的时间限制提高到 15 秒后，沙箱得以启动、运行代码，并在恰好 5.7 秒内返回结果，这证明我们的限制行之有效，同时也没有压垮云基础设施。

⚙️ 安装与设置

你需要运行两个组件：后端服务和 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"
      }
    }
  }
}

注意：请务必替换路径，并提供已注资的 EVM 钱包密钥，以便 Claude 处理 x402 微交易。

🧰 可用的 MCP 工具

此服务会公开以下端点。调用前，Agent 必须评估所需能力和成本。

工具	成本（USDC）	输入	输出	使用场景
execute_code	0.10	有效的 Python 脚本字符串。	文本（stdout/stderr）。最大返回限制为 8KB。	在隔离的 Azure 沙盒中执行任意 Python 逻辑、复杂计算或数据排序。请勿用于本地 FS 操作。
sanitize_csv	0.25	原始、未格式化的 CSV 字符串。	JSON 数组。	处理空值（将 NaN 转换为 null）、规范化表头，并在建模前删除空行。
optimize_ga	0.50	数值数据的 JSON 数组。	优化后的模型参数和 MAPE 分数。	负载预测、预测建模或曲线拟合。采用比例变异，实现 MAPE 精度低于 1%。
generate_plot	0.30	坐标和图表配置的 JSON 数组。	成功字符串（文件已保存到本地）。	可视化数据，无需触及令牌生成限制或依赖本地 GUI。

🤖 系统提示词说明（面向开发者）

将此代码片段复制并粘贴到 Agent 的系统提示词或 .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 文件。