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