feat(agents): Phase3.1 工具/MCP权限沙箱(tool_policy) 白名单+预算熔断+每轮上限+后台管理UI [v2026.07.19.6]

VERSION

@@ -1 +1 @@
-v2026.07.19.5
+v2026.07.19.6

backend/python/app/api/admin/agents_admin.py

@@ -555,3 +555,56 @@ async def get_available_models(
             for m, p in models
         ]
     }
+
+
+# ============================================================
+# 3.1 tool_policy 沙箱：Agent 工具/MCP 权限策略
+# ============================================================
+class ToolPolicyModel(BaseModel):
+    tool_policy: Optional[dict] = None  # null = 清除策略（恢复默认允许全部）
+
+
+@router.get("/{agent_id}/tool-policy", summary="获取 Agent 工具策略")
+async def get_agent_tool_policy(
+    agent_id: str,
+    admin_user=Depends(get_current_admin),
+    db: Session = Depends(get_db),
+):
+    agent = db.query(MarketApp).filter(
+        MarketApp.id == agent_id, MarketApp.type == "agent"
+    ).first()
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent 不存在")
+    return {"agent_id": agent_id, "tool_policy": agent.tool_policy}
+
+
+@router.put("/{agent_id}/tool-policy", summary="设置 Agent 工具策略")
+async def set_agent_tool_policy(
+    agent_id: str,
+    body: ToolPolicyModel,
+    admin_user=Depends(get_current_admin),
+    db: Session = Depends(get_db),
+):
+    agent = db.query(MarketApp).filter(
+        MarketApp.id == agent_id, MarketApp.type == "agent"
+    ).first()
+    if not agent:
+        raise HTTPException(status_code=404, detail="Agent 不存在")
+    tp = body.tool_policy
+    if tp is not None:
+        if not isinstance(tp, dict):
+            raise HTTPException(status_code=400, detail="tool_policy 必须为对象")
+        # 轻量结构校验
+        if "allowed_tools" in tp and tp["allowed_tools"] is not None:
+            at = tp["allowed_tools"]
+            if not isinstance(at, dict):
+                raise HTTPException(status_code=400, detail="allowed_tools 必须为对象")
+            for k in ("skill_ids", "mcp_ids"):
+                if k in at and at[k] is not None and not isinstance(at[k], list):
+                    raise HTTPException(status_code=400, detail=f"allowed_tools.{k} 必须为数组")
+        for k in ("max_calls_per_conversation", "per_round_cap"):
+            if k in tp and tp[k] is not None and not isinstance(tp[k], int):
+                raise HTTPException(status_code=400, detail=f"{k} 必须为整数")
+    agent.tool_policy = tp
+    db.commit()
+    return {"agent_id": agent_id, "tool_policy": agent.tool_policy, "updated": True}

backend/python/app/api/chat_service.py

@@ -1083,7 +1083,11 @@ async def _send_message_core(
 
 
 
+                    # ===== 3.1 tool_policy 沙箱：聚合策略 + 初始化预算计数器 =====
+                    _agent_tool_policy = _resolve_agent_tool_policy(agents)
+                    _tool_call_count = 0
                     for round_num in range(max_tool_rounds):
+                        _round_tool_count = 0
 
 
 
@@ -1297,6 +1301,26 @@ async def _send_message_core(
 
 
                                     func_name = tc.get("function", {}).get("name", "")
+                                    # ===== 3.1 tool_policy 沙箱：逐工具校验（白名单 + 预算 + 每轮上限） =====
+                                    _mcp_info = mcp_tool_map.get(func_name) if func_name.startswith("mcp_tool_") else None
+                                    _policy_check = _check_tool_policy(func_name, _mcp_info, skills, _agent_tool_policy, _tool_call_count, _round_tool_count)
+                                    if not _policy_check["allowed"]:
+                                        _reason = _policy_check["reason"]
+                                        logger.warning(
+                                            f"[tool_policy] blocked tool call: agent={_agent_tool_policy.get('agent_id') if _agent_tool_policy else None} "
+                                            f"tool={func_name} reason={_reason} trace={get_trace_id()}"
+                                        )
+                                        tool_result = f"[工具调用已被策略拦截] {_policy_check.get('message', _reason)}"
+                                        messages.append({
+                                            "role": "tool",
+                                            "tool_call_id": tc.get("id", f"call_{round_num}"),
+                                            "content": tool_result,
+                                        })
+                                        _tool_call_count += 1
+                                        _round_tool_count += 1
+                                        continue
+                                    _tool_call_count += 1
+                                    _round_tool_count += 1
 
 
 
@@ -2009,3 +2033,58 @@ async def _send_message_core(
 
 
     }
+
+
+# ======================================================================
+# 3.1 tool_policy 沙箱辅助函数
+# ======================================================================
+def _resolve_agent_tool_policy(agents):
+    """从已解析的 agents 聚合工具策略。多 agent 时取首个带有非空策略者。"""
+    if not agents:
+        return None
+    for ag in agents:
+        tp = ag.get("tool_policy")
+        if tp and isinstance(tp, dict):
+            tp = dict(tp)
+            tp["agent_id"] = ag.get("id")
+            return tp
+    return None
+
+
+def _check_tool_policy(func_name, mcp_info, skills, policy, call_count, round_count):
+    """校验单个工具调用是否被策略允许。
+
+    返回 {"allowed": bool, "reason": str, "tool_id": str|None, "message": str}
+    policy 为 None/空 -> 允许（向后兼容）。
+    """
+    if not policy:
+        return {"allowed": True, "tool_id": None}
+    allowed = policy.get("allowed_tools") or {}
+    skill_ids = allowed.get("skill_ids") or []
+    mcp_ids = allowed.get("mcp_ids") or []
+    is_mcp = func_name.startswith("mcp_tool_")
+    tool_id = None
+    if is_mcp:
+        if mcp_info and isinstance(mcp_info, dict):
+            tool_id = mcp_info.get("server_id")
+        if mcp_ids and tool_id not in mcp_ids:
+            return {"allowed": False, "reason": "mcp_not_in_allowlist", "tool_id": tool_id,
+                    "message": "MCP 服务不在该智能体的允许列表中"}
+    else:
+        if skills:
+            _s = next((s for s in skills if s.get("func_name") == func_name), None)
+            if _s:
+                tool_id = _s.get("id")
+        if skill_ids and tool_id not in skill_ids:
+            return {"allowed": False, "reason": "skill_not_in_allowlist", "tool_id": tool_id,
+                    "message": "技能不在该智能体的允许列表中"}
+    budget = policy.get("max_calls_per_conversation")
+    if budget is not None and call_count >= int(budget):
+        return {"allowed": False, "reason": "budget_exceeded", "tool_id": tool_id,
+                "message": policy.get("fallback_message")
+                or "该智能体已达到工具调用上限，请开启新对话或调整智能体设置。"}
+    per_round = policy.get("per_round_cap")
+    if per_round is not None and round_count >= int(per_round):
+        return {"allowed": False, "reason": "per_round_cap", "tool_id": tool_id,
+                "message": "本轮工具调用已达上限"}
+    return {"allowed": True, "tool_id": tool_id}

backend/python/app/api/chat_skill.py

@@ -513,6 +513,7 @@ def _resolve_market_agents(db: Session, agent_ids: list, user_id: str) -> list:
 
 
 
+            "tool_policy": ag.tool_policy,
             # 外部 Agent 接入(Dify/n8n/Coze)运行期远程调用所需字段：
 
 

backend/python/app/models.py

@@ -300,6 +300,7 @@ class MarketApp(Base):
     capability = Column(String(20), default=None, comment="能力分类：text/thinking/vision/tool/image/audio/asr/ocr/embedding/rerank/video")
     agent_endpoint = Column(String(500), default=None)
     agent_api_key = Column(String(500), default=None, comment="单个Agent接入的API Key")
+    tool_policy = Column(JSON, default=None, comment="Agent 工具/MCP 权限沙箱策略(3.1)")
     created_at = Column(DateTime, default=datetime.now)
     updated_at = Column(DateTime, default=datetime.now, onupdate=datetime.now)
 

frontend/src/api/index.ts

@@ -887,6 +887,10 @@ export const adminAPI = {
 
   getAdminAgentReviews: (id: string) => get<any>(`/admin/agents/${id}/reviews`),
 
+  // Phase 3.1: 工具/MCP 权限沙箱 (tool_policy)
+  getAgentToolPolicy: (id: string) => get<any>(`/admin/agents/${id}/tool-policy`),
+  setAgentToolPolicy: (id: string, toolPolicy: any) => put<any>(`/admin/agents/${id}/tool-policy`, { tool_policy: toolPolicy }),
+
   getAdminAvailableSkills: (params?: any) => {
 
     const query = params ? '?' + Object.entries(params).filter(([_, v]) => v !== undefined && v !== '').map(([k, v]) => `${k}=${v}`).join('&') : '';

frontend/src/pages/admin/Agents.tsx

@@ -105,6 +105,10 @@ const Agents: React.FC = () => {
   // Available skills for linking
   const [availableSkills, setAvailableSkills] = useState<any[]>([]);
   const [availableModels, setAvailableModels] = useState<AvailableModel[]>([]);
+  // Available MCP servers for tool_policy sandbox allowlist
+  const [availableMcps, setAvailableMcps] = useState<any[]>([]);
+  // Tool policy (sandbox) — null means disabled / no policy
+  const [toolPolicy, setToolPolicy] = useState<any>(null);
 
   // Toast
   const [toast, setToast] = useState<{ msg: string; type: 'success' | 'error' } | null>(null);
@@ -144,14 +148,17 @@ const Agents: React.FC = () => {
   // Load available skills & models
   const loadAvailable = async () => {
     try {
-      const [skillsResult, modelsResult] = await Promise.all([
+      const [skillsResult, modelsResult, mcpsResult] = await Promise.all([
         adminAPI.getAdminAvailableSkills({ page_size: 50 }) as any,
         adminAPI.getAdminAvailableModels() as any,
+        adminAPI.getAdminMcpServers({ page_size: 50 }) as any,
       ]);
       const skills = (skillsResult.data || skillsResult).items || [];
       const models = (modelsResult.data || modelsResult) || [];
+      const mcps = (mcpsResult.data || mcpsResult).items || [];
       setAvailableSkills(skills);
       setAvailableModels(models);
+      setAvailableMcps(mcps);
     } catch {}
   };
 
@@ -187,6 +194,7 @@ const Agents: React.FC = () => {
       memory_enabled: false,
       reasoning_enabled: false,
     });
+    setToolPolicy(null);
     setShowModal(true);
   };
 
@@ -194,6 +202,7 @@ const Agents: React.FC = () => {
   const openEdit = async (agent: Agent) => {
     setEditingAgent(agent);
     await loadAvailable();
+    await openEditLoadPolicy(agent.id);
 
     const cfg = agent.config || {};
     setForm({
@@ -213,7 +222,15 @@ const Agents: React.FC = () => {
     setShowModal(true);
   };
 
-  // Open detail
+  // Fetch existing tool_policy (sandbox) for this agent
+  const openEditLoadPolicy = async (agentId: string) => {
+    try {
+      const tpRes = await adminAPI.getAgentToolPolicy(agentId) as any;
+      setToolPolicy(tpRes?.data?.tool_policy || null);
+    } catch {
+      setToolPolicy(null);
+    }
+  };
   const openDetail = async (agent: Agent) => {
     setDetailAgent(agent);
     setShowDetail(true);
@@ -246,7 +263,13 @@ const Agents: React.FC = () => {
     try {
       if (editingAgent) {
         await adminAPI.updateAdminAgent(editingAgent.id, payload);
-        showToast('Agent 已更新');
+        // Phase 3.1: persist tool_policy sandbox (null clears it)
+        try {
+          await adminAPI.setAgentToolPolicy(editingAgent.id, toolPolicy);
+          showToast('Agent 已更新');
+        } catch (pe: any) {
+          showToast(`Agent 已更新，但策略保存失败: ${pe.message || pe}`, 'error');
+        }
       } else {
         await adminAPI.createAdminAgent(payload);
         showToast('Agent 创建成功');
@@ -612,6 +635,87 @@ const Agents: React.FC = () => {
                   </div>
                 )}
               </div>
+              {editingAgent && (
+                <div style={{ gridColumn: '1 / -1' }}>
+                  <hr style={{ border: 'none', borderTop: '1px solid #E5E7EB', margin: '16px 0' }} />
+                  <div style={{ fontWeight: 600, marginBottom: 12 }}>🛡️ 工具权限沙箱 (tool_policy)</div>
+                  <label style={{ display: 'flex', alignItems: 'center', gap: 8, cursor: 'pointer', marginBottom: 12 }}>
+                    <input type="checkbox" checked={toolPolicy !== null} onChange={e => {
+                      if (e.target.checked) {
+                        setToolPolicy({ allowed_tools: { skill_ids: [], mcp_ids: [] }, max_calls_per_conversation: null, per_round_cap: null, fallback_message: '' });
+                      } else {
+                        setToolPolicy(null);
+                      }
+                    }} />
+                    启用工具/MCP 权限沙箱（限制该 Agent 可调用的工具与调用频次）
+                  </label>
+                  {toolPolicy && (
+                    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+                      <div className="form-group" style={{ marginBottom: 0 }}>
+                        <label className="form-label">允许调用的技能（不选 = 禁止调用任何技能）</label>
+                        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6, maxHeight: 160, overflowY: 'auto', padding: 8, border: '1px solid #E5E7EB', borderRadius: 6 }}>
+                          {availableSkills.length === 0 ? (
+                            <span style={{ color: '#9CA3AF', fontSize: 13 }}>暂无技能</span>
+                          ) : availableSkills.map((skill: any) => {
+                            const checked = (toolPolicy.allowed_tools?.skill_ids || []).includes(skill.id);
+                            return (
+                              <label key={skill.id} style={{ display: 'flex', alignItems: 'center', gap: 4, padding: '4px 10px', borderRadius: 12, fontSize: 12, cursor: 'pointer', background: checked ? '#EEF2FF' : '#F9FAFB', border: `1px solid ${checked ? '#6366F1' : '#E5E7EB'}`, color: checked ? '#6366F1' : '#374151' }}>
+                                <input type="checkbox" style={{ display: 'none' }} checked={checked} onChange={() => {
+                                  const cur = toolPolicy.allowed_tools?.skill_ids || [];
+                                  const next = checked ? cur.filter((x: string) => x !== skill.id) : [...cur, skill.id];
+                                  setToolPolicy({ ...toolPolicy, allowed_tools: { ...(toolPolicy.allowed_tools || {}), skill_ids: next } });
+                                }} />
+                                {skill.skill_name}
+                              </label>
+                            );
+                          })}
+                        </div>
+                      </div>
+                      <div className="form-group" style={{ marginBottom: 0 }}>
+                        <label className="form-label">允许调用的 MCP 服务（不选 = 禁止调用任何 MCP）</label>
+                        <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6, maxHeight: 160, overflowY: 'auto', padding: 8, border: '1px solid #E5E7EB', borderRadius: 6 }}>
+                          {availableMcps.length === 0 ? (
+                            <span style={{ color: '#9CA3AF', fontSize: 13 }}>暂无 MCP 服务</span>
+                          ) : availableMcps.map((m: any) => {
+                            const checked = (toolPolicy.allowed_tools?.mcp_ids || []).includes(m.id);
+                            return (
+                              <label key={m.id} style={{ display: 'flex', alignItems: 'center', gap: 4, padding: '4px 10px', borderRadius: 12, fontSize: 12, cursor: 'pointer', background: checked ? '#EEF2FF' : '#F9FAFB', border: `1px solid ${checked ? '#6366F1' : '#E5E7EB'}`, color: checked ? '#6366F1' : '#374151' }}>
+                                <input type="checkbox" style={{ display: 'none' }} checked={checked} onChange={() => {
+                                  const cur = toolPolicy.allowed_tools?.mcp_ids || [];
+                                  const next = checked ? cur.filter((x: string) => x !== m.id) : [...cur, m.id];
+                                  setToolPolicy({ ...toolPolicy, allowed_tools: { ...(toolPolicy.allowed_tools || {}), mcp_ids: next } });
+                                }} />
+                                {m.name}
+                              </label>
+                            );
+                          })}
+                        </div>
+                      </div>
+                      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
+                        <div className="form-group" style={{ marginBottom: 0 }}>
+                          <label className="form-label">单对话最大调用次数（留空=不限制）</label>
+                          <input className="admin-form-input" type="number" min="0"
+                            value={toolPolicy.max_calls_per_conversation ?? ''}
+                            onChange={e => setToolPolicy({ ...toolPolicy, max_calls_per_conversation: e.target.value === '' ? null : parseInt(e.target.value) })} />
+                        </div>
+                        <div className="form-group" style={{ marginBottom: 0 }}>
+                          <label className="form-label">单轮最大调用次数（留空=不限制）</label>
+                          <input className="admin-form-input" type="number" min="0"
+                            value={toolPolicy.per_round_cap ?? ''}
+                            onChange={e => setToolPolicy({ ...toolPolicy, per_round_cap: e.target.value === '' ? null : parseInt(e.target.value) })} />
+                        </div>
+                      </div>
+                      <div className="form-group" style={{ marginBottom: 0 }}>
+                        <label className="form-label">额度耗尽提示语（可选）</label>
+                        <textarea className="admin-form-input" rows={2}
+                          value={toolPolicy.fallback_message || ''}
+                          onChange={e => setToolPolicy({ ...toolPolicy, fallback_message: e.target.value })}
+                          placeholder="例如：该智能体已达到工具调用上限，请开启新对话或调整智能体设置。" />
+                      </div>
+                    </div>
+                  )}
+                </div>
+              )}
             </div>
             <div className="modal-footer">
               <button className="admin-btn" onClick={() => setShowModal(false)}>取消</button>

migrations/022_add_tool_policy.sql

@@ -0,0 +1,15 @@
+-- Phase 3.1: MarketApp 增加 tool_policy（Agent 工具/MCP 权限沙箱策略）
+-- 幂等：仅当列不存在时才 ALTER
+SET @db = 'aiflow';
+SET @tbl = 'market_apps';
+SET @col = 'tool_policy';
+SET @exists = (
+    SELECT COUNT(*) FROM information_schema.columns
+    WHERE table_schema = @db AND table_name = @tbl AND column_name = @col
+);
+SET @sql = IF(@exists = 0,
+    'ALTER TABLE market_apps ADD COLUMN tool_policy JSON NULL',
+    'SELECT 1');
+PREPARE stmt FROM @sql;
+EXECUTE stmt;
+DEALLOCATE PREPARE stmt;