做計算化學和材料計算的朋友大多有過這樣的體驗一個結構優(yōu)化的任務從建模、選泛函、設收斂標準、跑任務、看軌跡、判斷是否收斂到最后一堆能量文件需要手工整理成表。整個鏈路里真正需要人做判斷的環(huán)節(jié)其實只有幾個剩下的全是重復勞動和格式轉換。而偏偏這幾個判斷環(huán)節(jié)又強依賴經(jīng)驗新人很難獨立完成。這篇文章想聊的就是能不能用 AI Agent 把這套鏈路串起來讓模型負責決定下一步做什么讓程序負責真正去做。文章會從概念講起然后手寫一個不依賴任何黑盒框架的最小 Agent用 ASE 內(nèi)置的 EMT 計算器跑通建?！獌?yōu)化—校驗—落盤的完整閉環(huán)最后再討論怎么把這個玩具級實現(xiàn)擴展到真實的第一性原理計算和機器學習勢場景。適合有 Python 基礎、做過一些原子尺度模擬、想了解 Agent 工程化的讀者。1. 為什么要把 AI Agent 引入計算化學與材料計算1.1 Agent 在這個語境下到底指什么先把這個詞說清楚因為它在不同圈子里含義差別很大。在這里AI Agent 指的是一個由大語言模型驅(qū)動的決策循環(huán)模型讀取當前的任務狀態(tài)從一組預先定義好的工具里挑選一個調(diào)用拿到工具返回的結構化結果再決定下一步如此往復直到任務結束或者觸發(fā)終止條件。它和用 ChatGPT 問一句然后復制粘貼結果有本質(zhì)區(qū)別。后者模型只是一次性地產(chǎn)生文本所有執(zhí)行動作由人完成前者模型處在一個閉環(huán)里它的每一次輸出都會被程序解析成具體的函數(shù)調(diào)用執(zhí)行結果又會回到模型的上下文里。換句話說Agent 的價值不在于模型懂多少化學而在于它能把意圖翻譯成操作序列并且根據(jù)中間結果動態(tài)調(diào)整。在計算化學和材料學里這個特性的用處非常明顯。因為這類任務的本質(zhì)是搜索——搜索構型空間、搜索參數(shù)組合、搜索收斂路徑。人的經(jīng)驗本質(zhì)上是一套啟發(fā)式規(guī)則而 Agent 恰好可以把這套規(guī)則形式化成工具調(diào)用序列同時保留在遇到異常時改弦更張的能力。需要強調(diào)的是Agent 不是萬能的。凡是需要高精度數(shù)值判斷的地方比如某個泛函對某類體系的系統(tǒng)性誤差模型基本給不出可靠結論。它的定位應該是實驗記錄員 操作員而不是理論家。1.2 與傳統(tǒng)腳本、工作流引擎的區(qū)別很多人會問我寫一個 Python 腳本把 ASE 的步驟串起來不就完了或者用工作流引擎編排一下這三者的差別值得掰開講。傳統(tǒng)腳本是確定性的路徑寫死。好處是可復現(xiàn)、易調(diào)試壞處是遇到邊界情況就崩比如某個元素 EMT 不支持、某個晶格常數(shù)導致優(yōu)化發(fā)散腳本沒法自己繞過去只能人來改代碼或者改參數(shù)。工作流引擎比如各種 DAG 編排工具解決了任務依賴和失敗重試的問題但它的分支邏輯依然是人預先寫死的。你可以配失敗了重試三次但沒法配如果能量異常升高就換個初始晶格常數(shù)再試。這類判斷需要語義理解工作流引擎做不到。Agent 補的正是這一塊把分支決策交給模型。代價是引入了不確定性——同樣的輸入模型兩次可能給出不同的操作序列。所以在工程上一個靠譜的 Agent 系統(tǒng)必須有確定性的校驗層兜底這一點后面會反復提到。一個實用的判斷標準是如果你的任務流程完全固定、輸入格式完全可控那就老老實實寫腳本別上 Agent。如果你的任務需要看情況比如結構來源五花八門、收斂行為不可預測、需要根據(jù)中間結果選下一步那 Agent 才有發(fā)揮空間。1.3 計算材料學里適合 Agent 化的任務不是所有任務都值得 Agent 化。根據(jù)實際使用情況下面這幾類收益比較明顯。第一類是結構準備與預處理。從 CIF、POSCAR、SMILES 等各種來源讀入結構判斷晶胞是否合理、是否需要加真空層、是否需要擴胞、表面模型該切哪個晶面。這些判斷規(guī)則性強但情況瑣碎很適合交給 Agent 調(diào)度。第二類是計算流程編排。給定一個體系和一個目標比如算彈性常數(shù)或算形成能Agent 需要拆解成一系列計算任務決定順序檢查每一步的輸出是否正常異常時調(diào)整參數(shù)重跑。第三類是結果解析與匯總。從大量輸出文件里提取能量、力、帶隙、晶格常數(shù)等量做單位換算整理成表格標注異常值。這類工作純體力活Agent 做起來出錯率反而比人低。第四類是文獻與數(shù)據(jù)庫的信息抽取輔助。比如從材料數(shù)據(jù)庫批量拉取結構并做一致性檢查。注意這里說的是輔助涉及判斷的部分仍然需要人復核。反過來純粹的精度評估、方法選擇的理論論證、需要長期經(jīng)驗的誤差分析這些不建議交給 Agent至少不能讓它做最終決策。2. 環(huán)境準備與項目骨架2.1 運行環(huán)境與依賴說明本文示例以 Python 環(huán)境為例。Python 版本建議 3.9 以上因為代碼里用了一些較新的類型標注寫法from __future__ import annotations可以兼容低版本但為了少踩坑建議直接用較新的小版本。核心依賴只有兩個方向計算側和編排側。計算側本文用 ASEAtomic Simulation Environment它自帶的 EMT 計算器可以對部分金屬做快速近似計算正好適合做演示不需要安裝任何第一性原理軟件。編排側如果要接真實大模型需要對應的 SDK如果只想先把流程跑通可以完全不用本文提供了一個離線的腳本化 Planner。需要說明的是具體依賴版本請以你本地環(huán)境的實際情況為準本文重點演示的是架構和配置思路不綁定某個特定版本號。安裝命令大致如下# 建議在虛擬環(huán)境中操作 python -m venv venv source venv/bin/activate # Windows 下用 venv\Scripts\activate # 計算側依賴 pip install ase numpy # 可選如果需要接大模型再安裝對應 SDK版本以官方文檔為準 # pip install openaiASE 的 EMT 計算器支持的元素有限主要覆蓋 Al、Cu、Ag、Au、Ni、Pd、Pt、H、C、N、O 等常見元素的一部分。如果你的體系包含它不支持的元素跑起來會直接報錯。這一點在演示階段要特別注意后面常見問題一節(jié)會專門講這個報錯怎么排查。2.2 項目目錄結構為了讓代碼可維護建議一開始就把結構分清楚。工具層負責真正干活Agent 層負責調(diào)度校驗層負責兜底三者不要混在一個文件里。推薦的結構如下chem-agent/ ├── agent/ │ ├── __init__.py │ ├── session.py # 計算會話持有當前結構等狀態(tài) │ ├── tools.py # 工具函數(shù)實現(xiàn) │ ├── schema.py # 工具描述給模型看的 │ ├── validators.py # 結果校驗 │ └── loop.py # Agent 主循環(huán) ├── planners/ │ ├── __init__.py │ ├── scripted.py # 離線規(guī)則 Planner用于測試 │ └── llm.py # 大模型 Planner可選 ├── runs/ # 運行產(chǎn)物自動創(chuàng)建 └── main.py # 入口這個劃分的好處是計算邏輯tools.py完全不感知模型的存在可以被普通腳本直接調(diào)用也可以在 Agent 里被調(diào)用。這一點非常重要因為它意味著你的計算代碼永遠可以獨立測試不會因為模型抽風而不可用。2.3 單位約定在動手寫代碼之前必須先把單位約定固定下來否則后面一定亂。ASE 內(nèi)部統(tǒng)一使用 eV 作為能量單位、? 作為長度單位、eV/? 作為力的單位。工具函數(shù)的入?yún)⒑头祷刂刀甲裱@套約定不要在中途混入 kcal/mol 或者 Hartree。如果最終要和其他軟件對接單位換算放在結果輸出環(huán)節(jié)統(tǒng)一做不要在工具內(nèi)部做隱式轉換。這個原則看似啰嗦但在實際項目里能省掉大量對不上數(shù)的排查時間。3. 核心原理拆解一個可落地的 Agent 由什么組成3.1 四要素模型拋開各種框架的包裝一個能干活的計算 Agent 由四部分組成狀態(tài)State、工具Tools、決策器Planner、循環(huán)控制器Loop Controller。狀態(tài)是當前任務的全部上下文包括已構建的原子結構、已執(zhí)行的操作歷史、中間計算結果。在計算化學場景里狀態(tài)管理是最容易被低估的部分。因為原子結構是個復雜對象沒法直接塞進模型的上下文只能序列化成摘要信息元素組成、原子數(shù)、晶格參數(shù)、當前能量等傳給模型。工具是一組有明確輸入輸出的函數(shù)。每個工具應該只做一件事并且可以被獨立測試。工具設計得好不好直接決定了 Agent 的上限——模型再聰明如果工具粒度太粗比如一個工具直接跑完整套流程模型就沒有調(diào)度空間如果太細比如一個工具只移動一個原子模型會被淹沒在細節(jié)里。決策器負責根據(jù)當前狀態(tài)選擇下一步動作。它可以是規(guī)則腳本也可以是大模型。把它抽成接口的好處是開發(fā)階段用規(guī)則腳本跑通流程上線前再換成模型兩者可以隨時切換對比。循環(huán)控制器負責防止 Agent 跑飛。必須有最大步數(shù)限制、重復動作檢測、異常中斷機制。一個沒有終止條件的 Agent 是很危險的尤其是當工具會消耗真實計算資源的時候。3.2 工具契約設計的三條原則寫工具函數(shù)的時候有三條原則值得堅持。第一條參數(shù)用基本類型。模型輸出的參數(shù)是 JSON只能表達字符串、數(shù)字、布爾、數(shù)組、對象。所以工具參數(shù)不要設計成Atoms對象這種復雜類型而應該用symbolCu、a3.6這樣的基本類型在函數(shù)內(nèi)部再去構造對象。第二條返回值必須可序列化且有明確狀態(tài)標識。建議統(tǒng)一返回一個 dict里面至少包含status字段ok/error和必要的數(shù)值結果。出錯時不要拋異常穿透到循環(huán)層而是在工具內(nèi)部捕獲后返回{status: error, message: ...}。這樣模型能看到錯誤信息并自行調(diào)整而不是整個程序崩掉。這點是 Agent 和普通腳本在設計理念上最大的不同之一。第三條單位寫進描述里。工具的 description 字段里要明確寫出參數(shù)和返回值的單位比如能量單位 eV、力收斂判據(jù)單位 eV/?。模型對單位非常敏感描述里不寫清楚它很容易傳錯量級。3.3 循環(huán)控制與終止條件一個最基本的 Agent 循環(huán)如下把當前狀態(tài)和歷史整理成消息列表。交給決策器得到下一個動作。如果是終止動作結束循環(huán)并輸出結果。否則解析動作名和參數(shù)調(diào)用對應工具。記錄工具返回結果回到第 1 步。這里面有幾個必須設的護欄。最大步數(shù)限制比如 20 步防止無限循環(huán)重復動作檢測防止模型卡在同一個調(diào)用上工具執(zhí)行超時防止某個計算卡死異常動作工具名不存在、參數(shù)缺失要有明確的兜底返回而不是直接拋異常。在實際項目中還有一個容易被忽略的護欄狀態(tài)一致性檢查。比如模型調(diào)用了優(yōu)化結構之后又調(diào)用了讀取能量如果優(yōu)化失敗導致結構狀態(tài)不合法讀取能量就應該返回明確的錯誤而不是給出無意義的數(shù)值。3.4 校驗層為什么不能省這一點值得單獨強調(diào)。模型給出的操作序列在語義上可能是合理的但在數(shù)值上可能完全錯誤。比如它可能把晶格常數(shù) 3.6 寫成 36或者把力的收斂判據(jù) 0.05 寫成 5。這類錯誤如果直接傳給計算程序輕則白跑一次重則產(chǎn)生一堆垃圾數(shù)據(jù)污染結果庫。校驗層的作用就是在工具執(zhí)行前后做數(shù)值合理性檢查晶格常數(shù)是否在合理區(qū)間比如 2 到 10 ?、原子間距是否過近小于 0.5 ? 通常意味建模出錯、能量是否為有限值、優(yōu)化后的最大力是否真的低于判據(jù)。這些檢查寫起來不復雜但能讓整個系統(tǒng)的可靠性提升一個量級。后面實戰(zhàn)部分會把它們具體實現(xiàn)出來。4. 完整實戰(zhàn)搭建一個結構優(yōu)化 Agent4.1 初始化項目與依賴先創(chuàng)建目錄結構并寫一個空的__init__.py然后在agent/session.py里定義會話對象。這個對象是整段代碼的狀態(tài)中心。# 文件路徑agent/session.py from __future__ import annotations import os from typing import Any, Dict, List, Optional from ase import Atoms class ChemSession: 計算會話持有當前結構、歷史記錄和運行目錄。 def __init__(self, workdir: str runs): self.workdir workdir os.makedirs(self.workdir, exist_okTrue) self.atoms: Optional[Atoms] None self.energy: Optional[float] None self.max_force: Optional[float] None self.history: List[Dict[str, Any]] [] def require_atoms(self) - Atoms: 獲取當前結構沒有則拋出可被工具層捕獲的錯誤。 if self.atoms is None: raise RuntimeError(當前會話還沒有結構請先調(diào)用 build_bulk) return self.atoms def summary(self) - Dict[str, Any]: 生成給模型看的結構摘要不要塞完整坐標。 if self.atoms is None: return {has_structure: False} return { has_structure: True, formula: self.atoms.get_chemical_formula(), natoms: len(self.atoms), cell_lengths: [round(x, 4) for x in self.atoms.cell.lengths()], energy_eV: None if self.energy is None else round(self.energy, 6), max_force_eV_per_A: ( None if self.max_force is None else round(self.max_force, 6) ), } def log(self, step: int, action: str, payload: Dict[str, Any]) - None: self.history.append({step: step, action: action, payload: payload})注意summary()里只返回摘要而不是完整坐標這是刻意設計的。一個 100 原子的結構如果完整序列化進上下文會占用大量 token而且模型也看不懂坐標數(shù)組。摘要里給元素組成、原子數(shù)、晶格參數(shù)、當前能量已經(jīng)足夠支撐決策了。4.2 編寫核心工具函數(shù)接下來是工具層。每個函數(shù)都遵循前面說的契約基本類型參數(shù)、dict 返回值、錯誤內(nèi)部捕獲。# 文件路徑agent/tools.py from __future__ import annotations import json import os from typing import Any, Dict from ase.build import bulk from ase.calculators.emt import EMT from ase.io import write as ase_write from ase.optimize import BFGS from agent.session import ChemSession def build_bulk( session: ChemSession, symbol: str, crystalstructure: str fcc, a: float 3.6, ) - Dict[str, Any]: 按指定晶格常數(shù)構建體相結構。a 的單位是 ?。 try: if not (2.0 float(a) 10.0): return { status: error, message: f晶格常數(shù) {a} 不在合理區(qū)間 [2.0, 10.0] ?請檢查是否單位寫錯, } atoms bulk(symbol, crystalstructure, afloat(a), cubicTrue) session.atoms atoms session.energy None session.max_force None return { status: ok, formula: atoms.get_chemical_formula(), natoms: len(atoms), cell_lengths_A: [round(x, 4) for x in atoms.cell.lengths()], } except Exception as exc: # noqa: BLE001 return {status: error, message: f構建結構失敗: {exc}} def optimize( session: ChemSession, fmax: float 0.05, steps: int 200, ) - Dict[str, Any]: 使用 BFGS 做結構優(yōu)化。fmax 單位 eV/?。 try: atoms session.require_atoms() if not (1e-4 float(fmax) 1.0): return { status: error, message: f收斂判據(jù) {fmax} eV/? 不合理常見取值 0.01 ~ 0.1, } if not (1 int(steps) 2000): return {status: error, message: f步數(shù) {steps} 超出允許范圍} atoms.calc EMT() optimizer BFGS(atoms, logfileos.devnull) converged optimizer.run(fmaxfloat(fmax), stepsint(steps)) forces atoms.get_forces() max_force float((forces ** 2).sum(axis1).max() ** 0.5) energy float(atoms.get_potential_energy()) session.energy energy session.max_force max_force return { status: ok, converged: bool(converged), energy_eV: round(energy, 6), max_force_eV_per_A: round(max_force, 6), cell_lengths_A: [round(x, 4) for x in atoms.cell.lengths()], } except Exception as exc: # noqa: BLE001 return {status: error, message: f優(yōu)化失敗: {exc}} def get_state(session: ChemSession) - Dict[str, Any]: 讀取當前會話狀態(tài)摘要。 return {status: ok, **session.summary()} def save_structure(session: ChemSession, filename: str final.xyz) - Dict[str, Any]: 把當前結構寫入 runs 目錄返回絕對路徑。 try: atoms session.require_atoms() if os.path.basename(filename) ! filename: return {status: error, message: filename 不能包含路徑分隔符} path os.path.join(session.workdir, filename) ase_write(path, atoms) return {status: ok, path: os.path.abspath(path), natoms: len(atoms)} except Exception as exc: # noqa: BLE001 return {status: error, message: f寫入結構失敗: {exc}}這里有幾點值得解釋。BFGS的run()方法返回布爾值表示是否收斂這個返回值要透傳給模型因為模型需要據(jù)此判斷是繼續(xù)調(diào)大步數(shù)還是調(diào)整初始結構。logfileos.devnull是為了避免優(yōu)化過程刷屏實際項目中建議改成寫文件方便事后復盤。最大力的計算用了(forces ** 2).sum(axis1).max() ** 0.5這是對每行三個分量求平方和再開方得到每個原子的力矢量模長取最大值。注意不要寫成forces.max()那是對分量取最大物理意義完全不同。save_structure里對filename做了路徑分隔符檢查這是一個簡單但必要的安全邊界。如果不檢查模型完全可能傳入../../etc/passwd這種值。雖然這只是個演示項目但這種習慣要養(yǎng)成。4.3 注冊工具 Schema工具寫好了還要告訴模型有哪些工具、參數(shù)是什么。這里用標準的 function calling 格式組織。# 文件路徑agent/schema.py TOOL_SCHEMA [ { type: function, function: { name: build_bulk, description: ( 按給定晶格常數(shù)構建體相晶體結構。 參數(shù) a 的單位是埃(?)常見金屬約在 3.0 到 4.5 之間。 ), parameters: { type: object, properties: { symbol: {type: string, description: 元素符號如 Cu}, crystalstructure: { type: string, description: 晶體結構類型如 fcc、bcc、hcp, }, a: {type: number, description: 晶格常數(shù)單位 ?}, }, required: [symbol, a], }, }, }, { type: function, function: { name: optimize, description: 對當前結構做 BFGS 結構優(yōu)化返回最終能量和最大力。, parameters: { type: object, properties: { fmax: { type: number, description: 力的收斂判據(jù)單位 eV/?常用 0.05, }, steps: {type: integer, description: 最大優(yōu)化步數(shù)}, }, required: [], }, }, }, { type: function, function: { name: get_state, description: 讀取當前結構摘要包括組成、原子數(shù)、晶格常數(shù)、能量。, parameters: {type: object, properties: {}, required: []}, }, }, { type: function, function: { name: save_structure, description: 把當前結構保存為 xyz 文件到運行目錄。, parameters: { type: object, properties: { filename: {type: string, description: 文件名不要帶路徑} }, required: [filename], }, }, }, ]Schema 里的 description 是給模型看的寫得好不好直接影響調(diào)用準確率。經(jīng)驗是把單位、常見取值、參數(shù)間的依賴關系都寫進去模型出錯的概率會明顯下降。比如常見金屬約在 3.0 到 4.5 之間這句話能有效避免模型傳 36 這種量級錯誤。4.4 實現(xiàn) Agent 主循環(huán)主循環(huán)負責把 Planner、工具、會話串起來。這里刻意不依賴任何 Agent 框架就是為了讓每一步都看得見。# 文件路徑agent/loop.py from __future__ import annotations import json from typing import Any, Callable, Dict, List from agent.session import ChemSession from agent.tools import build_bulk, get_state, optimize, save_structure MAX_STEPS 20 class AgentLoop: def __init__(self, session: ChemSession, planner, max_steps: int MAX_STEPS): self.session session self.planner planner self.max_steps max_steps self.tool_registry: Dict[str, Callable[..., Dict[str, Any]]] { build_bulk: lambda **kw: build_bulk(session, **kw), optimize: lambda **kw: optimize(session, **kw), get_state: lambda **kw: get_state(session), save_structure: lambda **kw: save_structure(session, **kw), } self.recent_actions: List[str] [] self.trace: List[Dict[str, Any]] [] def _is_repeat(self, action_key: str) - bool: return len(self.recent_actions) 2 and self.recent_actions[-2:] [action_key, action_key] def run(self, task: str) - Dict[str, Any]: for step in range(1, self.max_steps 1): decision self.planner.next_action(tasktask, stateself.session.summary()) if decision.get(name) finish: self.trace.append({step: step, action: finish, payload: decision}) return {status: ok, steps: step, answer: decision.get(arguments, {}), trace: self.trace} name decision.get(name, ) args decision.get(arguments, {}) or {} action_key f{name}:{json.dumps(args, sort_keysTrue)} if name not in self.tool_registry: result {status: error, message: f未知工具: {name}} elif self._is_repeat(action_key): result {status: error, message: 檢測到連續(xù)重復調(diào)用請換一個動作} else: try: result self.tool_registry[name](**args) except TypeError as exc: result {status: error, message: f參數(shù)不匹配: {exc}} except Exception as exc: # noqa: BLE001 result {status: error, message: f工具執(zhí)行異常: {exc}} self.recent_actions.append(action_key) self.session.log(step, name, {args: args, result: result}) self.trace.append({step: step, action: name, args: args, result: result}) return {status: timeout, message: f超過最大步數(shù) {self.max_steps}, trace: self.trace}幾個細節(jié)說明。tool_registry里用 lambda 把 session 閉包進去這樣 Planner 只需要關心業(yè)務參數(shù)不需要處理 session。_is_repeat檢測連續(xù)兩次完全相同的調(diào)用這是最常見的卡死場景——模型看不到進展就一直重復同一個動作。TypeError單獨捕獲是因為參數(shù)不匹配在 Agent 場景里極其常見需要給模型明確的錯誤提示讓它自我修正。另外注意返回值里帶了完整trace這個在調(diào)試時非常有用可以看到模型每一步的原始決策。生產(chǎn)環(huán)境里應該把它寫進日志文件而不是直接返回給用戶。4.5 兩個 Planner離線腳本與大模型先寫一個離線的腳本化 Planner用于在不接大模型的情況下驗證整條鏈路。# 文件路徑planners/scripted.py from __future__ import annotations from typing import Any, Dict, List class ScriptedPlanner: 按預設腳本順序返回動作用于離線聯(lián)調(diào)和回歸測試。 def __init__(self, script: List[Dict[str, Any]]): self.script list(script) self.cursor 0 def next_action(self, task: str, state: Dict[str, Any]) - Dict[str, Any]: if self.cursor len(self.script): return {name: finish, arguments: {summary: 腳本執(zhí)行完畢}} action self.script[self.cursor] self.cursor 1 return action對應的入口腳本# 文件路徑main.py from agent.loop import AgentLoop from agent.session import ChemSession from planners.scripted import ScriptedPlanner SCRIPT [ {name: build_bulk, arguments: {symbol: Cu, crystalstructure: fcc, a: 3.6}}, {name: get_state, arguments: {}}, {name: optimize, arguments: {fmax: 0.05, steps: 200}}, {name: get_state, arguments: {}}, {name: save_structure, arguments: {filename: cu_final.xyz}}, {name: finish, arguments: {summary: Cu 結構優(yōu)化完成}}, ] def main() - None: session ChemSession(workdirruns) loop AgentLoop(session, ScriptedPlanner(SCRIPT)) result loop.run(task優(yōu)化 fcc Cu 的晶格常數(shù)) for item in result.get(trace, []): print(item) if __name__ __main__: main()運行之后預期能看到這樣一串輸出先構建出含 4 個原子的 fcc 銅晶胞cubicTrue會生成常規(guī)立方胞然后優(yōu)化幾步能量大約在 -0.02 eV/atom 量級EMT 的絕對值本身沒有物理意義只看相對變化最后在當前目錄下生成runs/cu_final.xyz。如果要在真實場景里換成大模型Planner 需要實現(xiàn)同樣的next_action接口。核心邏輯是把工具 schema 一起傳給模型然后解析返回的 tool_calls# 文件路徑planners/llm.py from __future__ import annotations import json from typing import Any, Dict, List from agent.schema import TOOL_SCHEMA # 說明以下為調(diào)用思路示例SDK 版本與方法名請以官方文檔為準 class LLMPlanner: def __init__(self, client, model: str, system_prompt: str ): self.client client self.model model self.messages: List[Dict[str, Any]] [] self.system_prompt system_prompt or ( 你是一個計算材料學助手。你只能通過提供的工具操作結構 不要憑空給出數(shù)值結果。每次只調(diào)用一個工具。 ) def next_action(self, task: str, state: Dict[str, Any]) - Dict[str, Any]: if not self.messages: self.messages.append({role: system, content: self.system_prompt}) self.messages.append( { role: user, content: f任務{(diào)task}\n當前狀態(tài){json.dumps(state, ensure_asciiFalse)}, } ) response self.client.chat.completions.create( modelself.model, messagesself.messages, toolsTOOL_SCHEMA, tool_choiceauto, ) message response.choices[0].message self.messages.append(message.model_dump() if hasattr(message, model_dump) else message) if not getattr(message, tool_calls, None): return {name: finish, arguments: {summary: message.content}} call message.tool_calls[0] try: arguments json.loads(call.function.arguments or {}) except json.JSONDecodeError: arguments {} return {name: call.function.name, arguments: arguments} def observe(self, result: Dict[str, Any]) - None: 把工具結果回填到消息歷史供下一輪決策使用。 self.messages.append( {role: tool, content: json.dumps(result, ensure_asciiFalse)} )這里要提醒一句不同版本 SDK 的工具調(diào)用回填格式不完全一樣tool消息通常需要帶tool_call_id。實際接入時請對照官方文檔調(diào)整不要直接照抄。這也是本文故意把 Planner 抽成接口的原因——換個模型或者換個 SDK只需要改這一個文件。4.6 加入校驗層前面說的校驗層現(xiàn)在補上。它的作用是攔截那些看起來能跑但結果沒意義的情況。# 文件路徑agent/validators.py from __future__ import annotations import math from typing import Any, Dict from ase import Atoms def check_structure(atoms: Atoms, min_distance: float 0.5) - Dict[str, Any]: 檢查結構的基本合理性返回校驗結論。 issues [] if len(atoms) 0: issues.append(結構中沒有原子) cell_lengths atoms.cell.lengths() if any(x 0 for x in cell_lengths): issues.append(f晶胞長度異常: {cell_lengths}) distances atoms.get_all_distances(micTrue) for i in range(len(atoms)): for j in range(i 1, len(atoms)): if distances[i][j] min_distance: issues.append( f原子 {i} 與 {j} 距離 {distances[i][j]:.3f} ? 過近疑似建模錯誤 ) return {ok: not issues, issues: issues} def check_energy(energy: float) - Dict[str, Any]: 檢查能量是否為有限值。 if energy is None: return {ok: False, issues: [能量為空]} if not math.isfinite(energy): return {ok: False, issues: [f能量不是有限值: {energy}]} return {ok: True, issues: []}get_all_distances(micTrue)里的mic表示使用最小鏡像約定對周期性體系這是必要的否則會誤判跨邊界的原子距離。這個檢查在擴胞、切表面之后特別有用能抓出很多建模錯誤。把校驗接進優(yōu)化流程可以在optimize工具里返回值加一個validation字段也可以在循環(huán)層統(tǒng)一做。實踐上更推薦在工具內(nèi)部做因為工具知道自己的語義。5. 從演示走向生產(chǎn)擴展方向5.1 接入第一性原理計算與機器學習勢演示用的是 EMT速度極快但沒有精度。真實場景里通常要換成第一性原理計算器或機器學習勢。ASE 的好處是接口統(tǒng)一只要計算器實現(xiàn)了get_potential_energy和get_forces上層代碼基本不用改。下面是一個示意寫法展示如何把計算器做成可配置的# 文件路徑agent/calculators.py from __future__ import annotations from ase.calculators.emt import EMT def make_calculator(name: str emt, **kwargs): 根據(jù)名稱返回計算器實例。真實項目里在這里分支到 VASP、CP2K 或機器學習勢。 name (name or emt).lower() if name emt: return EMT() # 其他計算器請按實際安裝情況補充例如 # if name mace: # from mace.calculators import mace_mp # return mace_mp(modelkwargs.get(model, medium)) raise ValueError(f不支持的計算器: {name})這里的關鍵設計是把計算器選擇也變成一個參數(shù)讓 Agent 可以在成本和質(zhì)量之間做權衡。比如粗篩階段用機器學習勢最后精修用第一性原理。這種分階段策略在真實項目里非常常見因為它能把計算成本降下來一大截。需要提醒的是真正的第一性原理計算動輒幾十分鐘到幾小時Agent 的循環(huán)必須支持異步——不能讓整個進程阻塞等待。實踐做法是把任務提交到作業(yè)調(diào)度系統(tǒng)工具返回一個作業(yè) ID然后另設一個查詢工具輪詢狀態(tài)。這樣 Agent 的循環(huán)節(jié)奏和計算任務的生命周期就解耦了。5.2 批量任務與結果匯總單個結構的優(yōu)化只是起點。真實場景往往是幾十上百個結構這時候 Agent 的角色就變成了調(diào)度員決定先跑哪些、哪些失敗需要重試、哪些結果異常需要人工復核。批量場景下最重要的工程點是冪等性和緩存。每個結構用內(nèi)容哈希做 key算過的直接讀緩存不要重復算。這一步能省掉大量算力也能讓整個流程可以斷點續(xù)跑。結果匯總建議輸出結構化格式JSON 或 CSV字段固定不要用自然語言描述結果。自然語言適合給模型讀不適合給人做后續(xù)分析。5.3 讓 Agent 輸出可復現(xiàn)的記錄一個容易被忽略的要求Agent 的每一次運行都應該產(chǎn)出一份可復現(xiàn)的記錄包括任務描述、模型版本、工具調(diào)用序列、每個工具的輸入輸出、最終結果。這份記錄的價值在于當結果出現(xiàn)爭議時你可以一層層回溯到底是哪一步出了問題。實踐上可以把前面循環(huán)里的trace直接序列化成 JSON 落盤文件名帶上時間戳。如果接了真實模型建議把模型的原始響應也存下來方便排查是模型的問題還是解析的問題。6. 常見問題與排查清單6.1 高頻問題對照表問題現(xiàn)象常見原因解決思路報錯說某元素沒有對應的 EMT 參數(shù)EMT 計算器只支持部分元素換用支持該元素的計算器或在工具層做元素白名單校驗并提前返回明確錯誤優(yōu)化跑完converged為 False初始結構離平衡位置太遠、步數(shù)不夠、判據(jù)過嚴先放寬 fmax 到 0.1 粗優(yōu)化再收緊到 0.02 精優(yōu)化或調(diào)整初始晶格常數(shù)能量出現(xiàn)nan或極大正值原子重疊、晶胞退化、計算器參數(shù)缺失用check_structure檢查最小原子間距確認晶胞長度為正模型反復調(diào)用同一個工具工具返回值沒有提供新信息模型無法判斷進展檢查工具返回是否包含關鍵數(shù)值在主循環(huán)加重復動作檢測并返回提示工具調(diào)用報參數(shù)不匹配模型傳了多余參數(shù)或類型不對在循環(huán)里捕獲TypeError把錯誤信息回填給模型同時精簡 schema 的 required 字段優(yōu)化后晶格常數(shù)幾乎沒變用了固定晶胞的自由度設置只優(yōu)化了原子位置明確是否需要優(yōu)化晶胞ASE 中 BFGS 默認會優(yōu)化所有自由度但需確認Atoms是否帶正確的 pbc結果每次跑都不完全一樣初始結構不同、優(yōu)化器隨機性、并行歸約順序固定初始結構來源、固定優(yōu)化器參數(shù)、記錄完整輸入保存文件時報路徑錯誤文件名包含路徑分隔符或非法字符在工具層做文件名白名單校驗只允許字母數(shù)字下劃線和點6.2 建議的排查順序遇到 Agent 跑飛的情況建議按這個順序查先看 trace 里最后一個成功的工具調(diào)用是什么確認狀態(tài)是否合法再看模型給出的參數(shù)是否在合理范圍然后單獨把那個工具函數(shù)拎出來脫離 Agent 手動調(diào)用一次確認計算本身沒問題最后才懷疑模型。這個順序能幫你快速區(qū)分計算問題和調(diào)度問題避免在錯誤的方向上浪費時間。一個很實用的技巧是準備一組固定的回歸用例幾個典型結構、幾組典型參數(shù)每次改動 Agent 邏輯后跑一遍確認結果沒變。Agent 系統(tǒng)的不確定性很強沒有回歸測試的話改一行代碼可能帶來完全意想不到的行為變化。7. 最佳實踐與工程建議7.1 工具粒度的把握工具粒度是設計 Agent 時最需要反復調(diào)整的地方。太粗模型沒有調(diào)度空間Agent 退化成一個固定腳本太細模型要在瑣碎操作上消耗大量 token 和步數(shù)。一個經(jīng)驗法則是一個工具對應一個物理上有意義的操作。構建結構、優(yōu)化結構、計算單點能、保存結構這些都是有明確物理含義的原子操作。而把第 3 個原子的 x 坐標加 0.1這種就不適合做成工具因為它不對應任何有意義的研究動作。另一個法則是如果一個操作幾乎總是跟著另一個操作出現(xiàn)考慮把它們合并。比如優(yōu)化并返回能量就比優(yōu)化和讀能量兩個工具更實用因為分開調(diào)用只會增加步數(shù)。7.2 安全邊界與資源控制涉及真實計算資源的場景安全邊界必須提前設計。至少要有這幾層文件寫入限制在指定目錄內(nèi)計算任務有超時和資源上限單次會話的總計算量有配額危險操作比如刪除文件、提交大規(guī)模作業(yè)需要顯式確認。不要指望模型自己遵守這些規(guī)則。模型的輸出是不可信的輸入所有約束必須在代碼層強制實施。這和 Web 開發(fā)里永遠不要信任前端傳參是同一個道理。7.3 可復現(xiàn)性與版本記錄計算科學最講究可復現(xiàn)。引入 Agent 之后可復現(xiàn)性面臨新的挑戰(zhàn)同一個任務模型可能給出不同的操作序列。應對辦法有兩個方向一是把所有輸入任務描述、模型版本、溫度參數(shù)、工具 schema 版本都記錄下來二是關鍵流程提供固化能力也就是把一次成功的 Agent 運行固化成腳本后續(xù)直接跑腳本。第二個方向在實際項目中價值很高。Agent 負責探索一旦找到可行路徑就固化成確定性流程既保留了靈活性又保證了穩(wěn)定性。7.4 日志與可觀測性建議給每次會話分配一個唯一 ID所有日志帶上這個 ID。日志內(nèi)容至少包括每步的動作名、參數(shù)、返回結果摘要、耗時。有了這些出問題時可以像查分布式系統(tǒng)調(diào)用鏈一樣回溯。另外建議對工具調(diào)用做耗時統(tǒng)計。如果某個工具平均耗時特別長說明它可能被調(diào)用得過于頻繁或者內(nèi)部有優(yōu)化空間。這類數(shù)據(jù)驅(qū)動的優(yōu)化比憑感覺調(diào)整有效得多。7.5 成本控制如果接的是商用大模型 APItoken 成本需要關注。控制手段主要有三個精簡 schema只保留必要工具和參數(shù)、精簡狀態(tài)摘要不要傳完整結構、限制歷史長度只保留最近若干輪對話。一個容易忽略的點是工具返回值的長度。如果工具返回了完整的坐標數(shù)組或者幾千行的輸出文件token 會瞬間爆掉。所有工具返回值都應該做摘要化處理只保留決策需要的數(shù)值。8. 學習路線與后續(xù)方向如果想把這條路走下去建議分三個階段推進。第一階段是把本文的演示跑通并且改造它。換幾個不同的元素和晶體結構故意傳入錯誤參數(shù)看系統(tǒng)怎么反應故意讓優(yōu)化不收斂看 Agent 能否自行調(diào)整。這個階段的目的是建立對整個鏈路的直覺。第二階段是接入真實計算。選一個你熟悉的小體系用你平時用的計算軟件跑一遍然后把同樣的流程用 Agent 封裝。這個階段會暴露大量工程細節(jié)問題作業(yè)提交、狀態(tài)輪詢、輸出解析、錯誤恢復。把這些問題解決掉系統(tǒng)才算真正可用。第三階段是做對比評估。用同一批任務分別用人工流程和 Agent 流程跑對比耗時、成本、結果一致性。只有在數(shù)據(jù)上站得住腳才值得推廣。需要提前提醒的風險有幾個。一是不要把 Agent 的輸出當成最終結論所有數(shù)值結果都必須經(jīng)過獨立校驗二是不要在未經(jīng)驗證的情況下讓它操作生產(chǎn)計算資源三是注意數(shù)據(jù)的合規(guī)性涉及未公開材料的計算數(shù)據(jù)不要隨意傳給外部服務。最后想說Agent 在計算材料學里的定位短期內(nèi)更像是熟練的科研助理而不是獨立研究者。它能把重復勞動接過去能幫你把流程標準化能減少低級錯誤但科學判斷的部分仍然需要人來把關。把這個定位想清楚落地的時候就不會有太多不切實際的期待也更容易做出真正有用的東西。