做计算化学和材料计算的朋友大多有过这样的体验一个结构优化的任务从建模、选泛函、设收敛标准、跑任务、看轨迹、判断是否收敛到最后一堆能量文件需要手工整理成表。整个链路里真正需要人做判断的环节其实只有几个剩下的全是重复劳动和格式转换。而偏偏这几个判断环节又强依赖经验新人很难独立完成。这篇文章想聊的就是能不能用 AI Agent 把这套链路串起来让模型负责决定下一步做什么让程序负责真正去做。文章会从概念讲起然后手写一个不依赖任何黑盒框架的最小 Agent用 ASE 内置的 EMT 计算器跑通建模—优化—校验—落盘的完整闭环最后再讨论怎么把这个玩具级实现扩展到真实的第一性原理计算和机器学习势场景。适合有 Python 基础、做过一些原子尺度模拟、想了解 Agent 工程化的读者。1. 为什么要把 AI Agent 引入计算化学与材料计算1.1 Agent 在这个语境下到底指什么先把这个词说清楚因为它在不同圈子里含义差别很大。在这里AI Agent 指的是一个由大语言模型驱动的决策循环模型读取当前的任务状态从一组预先定义好的工具里挑选一个调用拿到工具返回的结构化结果再决定下一步如此往复直到任务结束或者触发终止条件。它和用 ChatGPT 问一句然后复制粘贴结果有本质区别。后者模型只是一次性地产生文本所有执行动作由人完成前者模型处在一个闭环里它的每一次输出都会被程序解析成具体的函数调用执行结果又会回到模型的上下文里。换句话说Agent 的价值不在于模型懂多少化学而在于它能把意图翻译成操作序列并且根据中间结果动态调整。在计算化学和材料学里这个特性的用处非常明显。因为这类任务的本质是搜索——搜索构型空间、搜索参数组合、搜索收敛路径。人的经验本质上是一套启发式规则而 Agent 恰好可以把这套规则形式化成工具调用序列同时保留在遇到异常时改弦更张的能力。需要强调的是Agent 不是万能的。凡是需要高精度数值判断的地方比如某个泛函对某类体系的系统性误差模型基本给不出可靠结论。它的定位应该是实验记录员 操作员而不是理论家。1.2 与传统脚本、工作流引擎的区别很多人会问我写一个 Python 脚本把 ASE 的步骤串起来不就完了或者用工作流引擎编排一下这三者的差别值得掰开讲。传统脚本是确定性的路径写死。好处是可复现、易调试坏处是遇到边界情况就崩比如某个元素 EMT 不支持、某个晶格常数导致优化发散脚本没法自己绕过去只能人来改代码或者改参数。工作流引擎比如各种 DAG 编排工具解决了任务依赖和失败重试的问题但它的分支逻辑依然是人预先写死的。你可以配失败了重试三次但没法配如果能量异常升高就换个初始晶格常数再试。这类判断需要语义理解工作流引擎做不到。Agent 补的正是这一块把分支决策交给模型。代价是引入了不确定性——同样的输入模型两次可能给出不同的操作序列。所以在工程上一个靠谱的 Agent 系统必须有确定性的校验层兜底这一点后面会反复提到。一个实用的判断标准是如果你的任务流程完全固定、输入格式完全可控那就老老实实写脚本别上 Agent。如果你的任务需要看情况比如结构来源五花八门、收敛行为不可预测、需要根据中间结果选下一步那 Agent 才有发挥空间。1.3 计算材料学里适合 Agent 化的任务不是所有任务都值得 Agent 化。根据实际使用情况下面这几类收益比较明显。第一类是结构准备与预处理。从 CIF、POSCAR、SMILES 等各种来源读入结构判断晶胞是否合理、是否需要加真空层、是否需要扩胞、表面模型该切哪个晶面。这些判断规则性强但情况琐碎很适合交给 Agent 调度。第二类是计算流程编排。给定一个体系和一个目标比如算弹性常数或算形成能Agent 需要拆解成一系列计算任务决定顺序检查每一步的输出是否正常异常时调整参数重跑。第三类是结果解析与汇总。从大量输出文件里提取能量、力、带隙、晶格常数等量做单位换算整理成表格标注异常值。这类工作纯体力活Agent 做起来出错率反而比人低。第四类是文献与数据库的信息抽取辅助。比如从材料数据库批量拉取结构并做一致性检查。注意这里说的是辅助涉及判断的部分仍然需要人复核。反过来纯粹的精度评估、方法选择的理论论证、需要长期经验的误差分析这些不建议交给 Agent至少不能让它做最终决策。2. 环境准备与项目骨架2.1 运行环境与依赖说明本文示例以 Python 环境为例。Python 版本建议 3.9 以上因为代码里用了一些较新的类型标注写法from __future__ import annotations可以兼容低版本但为了少踩坑建议直接用较新的小版本。核心依赖只有两个方向计算侧和编排侧。计算侧本文用 ASEAtomic Simulation Environment它自带的 EMT 计算器可以对部分金属做快速近似计算正好适合做演示不需要安装任何第一性原理软件。编排侧如果要接真实大模型需要对应的 SDK如果只想先把流程跑通可以完全不用本文提供了一个离线的脚本化 Planner。需要说明的是具体依赖版本请以你本地环境的实际情况为准本文重点演示的是架构和配置思路不绑定某个特定版本号。安装命令大致如下# 建议在虚拟环境中操作 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 等常见元素的一部分。如果你的体系包含它不支持的元素跑起来会直接报错。这一点在演示阶段要特别注意后面常见问题一节会专门讲这个报错怎么排查。2.2 项目目录结构为了让代码可维护建议一开始就把结构分清楚。工具层负责真正干活Agent 层负责调度校验层负责兜底三者不要混在一个文件里。推荐的结构如下chem-agent/ ├── agent/ │ ├── __init__.py │ ├── session.py # 计算会话持有当前结构等状态 │ ├── tools.py # 工具函数实现 │ ├── schema.py # 工具描述给模型看的 │ ├── validators.py # 结果校验 │ └── loop.py # Agent 主循环 ├── planners/ │ ├── __init__.py │ ├── scripted.py # 离线规则 Planner用于测试 │ └── llm.py # 大模型 Planner可选 ├── runs/ # 运行产物自动创建 └── main.py # 入口这个划分的好处是计算逻辑tools.py完全不感知模型的存在可以被普通脚本直接调用也可以在 Agent 里被调用。这一点非常重要因为它意味着你的计算代码永远可以独立测试不会因为模型抽风而不可用。2.3 单位约定在动手写代码之前必须先把单位约定固定下来否则后面一定乱。ASE 内部统一使用 eV 作为能量单位、Å 作为长度单位、eV/Å 作为力的单位。工具函数的入参和返回值都遵循这套约定不要在中途混入 kcal/mol 或者 Hartree。如果最终要和其他软件对接单位换算放在结果输出环节统一做不要在工具内部做隐式转换。这个原则看似啰嗦但在实际项目里能省掉大量对不上数的排查时间。3. 核心原理拆解一个可落地的 Agent 由什么组成3.1 四要素模型抛开各种框架的包装一个能干活的计算 Agent 由四部分组成状态State、工具Tools、决策器Planner、循环控制器Loop Controller。状态是当前任务的全部上下文包括已构建的原子结构、已执行的操作历史、中间计算结果。在计算化学场景里状态管理是最容易被低估的部分。因为原子结构是个复杂对象没法直接塞进模型的上下文只能序列化成摘要信息元素组成、原子数、晶格参数、当前能量等传给模型。工具是一组有明确输入输出的函数。每个工具应该只做一件事并且可以被独立测试。工具设计得好不好直接决定了 Agent 的上限——模型再聪明如果工具粒度太粗比如一个工具直接跑完整套流程模型就没有调度空间如果太细比如一个工具只移动一个原子模型会被淹没在细节里。决策器负责根据当前状态选择下一步动作。它可以是规则脚本也可以是大模型。把它抽成接口的好处是开发阶段用规则脚本跑通流程上线前再换成模型两者可以随时切换对比。循环控制器负责防止 Agent 跑飞。必须有最大步数限制、重复动作检测、异常中断机制。一个没有终止条件的 Agent 是很危险的尤其是当工具会消耗真实计算资源的时候。3.2 工具契约设计的三条原则写工具函数的时候有三条原则值得坚持。第一条参数用基本类型。模型输出的参数是 JSON只能表达字符串、数字、布尔、数组、对象。所以工具参数不要设计成Atoms对象这种复杂类型而应该用symbolCu、a3.6这样的基本类型在函数内部再去构造对象。第二条返回值必须可序列化且有明确状态标识。建议统一返回一个 dict里面至少包含status字段ok/error和必要的数值结果。出错时不要抛异常穿透到循环层而是在工具内部捕获后返回{status: error, message: ...}。这样模型能看到错误信息并自行调整而不是整个程序崩掉。这点是 Agent 和普通脚本在设计理念上最大的不同之一。第三条单位写进描述里。工具的 description 字段里要明确写出参数和返回值的单位比如能量单位 eV、力收敛判据单位 eV/Å。模型对单位非常敏感描述里不写清楚它很容易传错量级。3.3 循环控制与终止条件一个最基本的 Agent 循环如下把当前状态和历史整理成消息列表。交给决策器得到下一个动作。如果是终止动作结束循环并输出结果。否则解析动作名和参数调用对应工具。记录工具返回结果回到第 1 步。这里面有几个必须设的护栏。最大步数限制比如 20 步防止无限循环重复动作检测防止模型卡在同一个调用上工具执行超时防止某个计算卡死异常动作工具名不存在、参数缺失要有明确的兜底返回而不是直接抛异常。在实际项目中还有一个容易被忽略的护栏状态一致性检查。比如模型调用了优化结构之后又调用了读取能量如果优化失败导致结构状态不合法读取能量就应该返回明确的错误而不是给出无意义的数值。3.4 校验层为什么不能省这一点值得单独强调。模型给出的操作序列在语义上可能是合理的但在数值上可能完全错误。比如它可能把晶格常数 3.6 写成 36或者把力的收敛判据 0.05 写成 5。这类错误如果直接传给计算程序轻则白跑一次重则产生一堆垃圾数据污染结果库。校验层的作用就是在工具执行前后做数值合理性检查晶格常数是否在合理区间比如 2 到 10 Å、原子间距是否过近小于 0.5 Å 通常意味建模出错、能量是否为有限值、优化后的最大力是否真的低于判据。这些检查写起来不复杂但能让整个系统的可靠性提升一个量级。后面实战部分会把它们具体实现出来。4. 完整实战搭建一个结构优化 Agent4.1 初始化项目与依赖先创建目录结构并写一个空的__init__.py然后在agent/session.py里定义会话对象。这个对象是整段代码的状态中心。# 文件路径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(当前会话还没有结构请先调用 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而且模型也看不懂坐标数组。摘要里给元素组成、原子数、晶格参数、当前能量已经足够支撑决策了。4.2 编写核心工具函数接下来是工具层。每个函数都遵循前面说的契约基本类型参数、dict 返回值、错误内部捕获。# 文件路径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]: 按指定晶格常数构建体相结构。a 的单位是 Å。 try: if not (2.0 float(a) 10.0): return { status: error, message: f晶格常数 {a} 不在合理区间 [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 做结构优化。fmax 单位 eV/Å。 try: atoms session.require_atoms() if not (1e-4 float(fmax) 1.0): return { status: error, message: f收敛判据 {fmax} eV/Å 不合理常见取值 0.01 ~ 0.1, } if not (1 int(steps) 2000): return {status: error, message: f步数 {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优化失败: {exc}} def get_state(session: ChemSession) - Dict[str, Any]: 读取当前会话状态摘要。 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()方法返回布尔值表示是否收敛这个返回值要透传给模型因为模型需要据此判断是继续调大步数还是调整初始结构。logfileos.devnull是为了避免优化过程刷屏实际项目中建议改成写文件方便事后复盘。最大力的计算用了(forces ** 2).sum(axis1).max() ** 0.5这是对每行三个分量求平方和再开方得到每个原子的力矢量模长取最大值。注意不要写成forces.max()那是对分量取最大物理意义完全不同。save_structure里对filename做了路径分隔符检查这是一个简单但必要的安全边界。如果不检查模型完全可能传入../../etc/passwd这种值。虽然这只是个演示项目但这种习惯要养成。4.3 注册工具 Schema工具写好了还要告诉模型有哪些工具、参数是什么。这里用标准的 function calling 格式组织。# 文件路径agent/schema.py TOOL_SCHEMA [ { type: function, function: { name: build_bulk, description: ( 按给定晶格常数构建体相晶体结构。 参数 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: 晶格常数单位 Å}, }, required: [symbol, a], }, }, }, { type: function, function: { name: optimize, description: 对当前结构做 BFGS 结构优化返回最终能量和最大力。, parameters: { type: object, properties: { fmax: { type: number, description: 力的收敛判据单位 eV/Å常用 0.05, }, steps: {type: integer, description: 最大优化步数}, }, required: [], }, }, }, { type: function, function: { name: get_state, description: 读取当前结构摘要包括组成、原子数、晶格常数、能量。, 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 是给模型看的写得好不好直接影响调用准确率。经验是把单位、常见取值、参数间的依赖关系都写进去模型出错的概率会明显下降。比如常见金属约在 3.0 到 4.5 之间这句话能有效避免模型传 36 这种量级错误。4.4 实现 Agent 主循环主循环负责把 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: 检测到连续重复调用请换一个动作} else: try: result self.tool_registry[name](**args) except TypeError as exc: result {status: error, message: f参数不匹配: {exc}} except Exception as exc: # noqa: BLE001 result {status: error, message: f工具执行异常: {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超过最大步数 {self.max_steps}, trace: self.trace}几个细节说明。tool_registry里用 lambda 把 session 闭包进去这样 Planner 只需要关心业务参数不需要处理 session。_is_repeat检测连续两次完全相同的调用这是最常见的卡死场景——模型看不到进展就一直重复同一个动作。TypeError单独捕获是因为参数不匹配在 Agent 场景里极其常见需要给模型明确的错误提示让它自我修正。另外注意返回值里带了完整trace这个在调试时非常有用可以看到模型每一步的原始决策。生产环境里应该把它写进日志文件而不是直接返回给用户。4.5 两个 Planner离线脚本与大模型先写一个离线的脚本化 Planner用于在不接大模型的情况下验证整条链路。# 文件路径planners/scripted.py from __future__ import annotations from typing import Any, Dict, List class ScriptedPlanner: 按预设脚本顺序返回动作用于离线联调和回归测试。 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: 脚本执行完毕}} 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 结构优化完成}}, ] def main() - None: session ChemSession(workdirruns) loop AgentLoop(session, ScriptedPlanner(SCRIPT)) result loop.run(task优化 fcc Cu 的晶格常数) for item in result.get(trace, []): print(item) if __name__ __main__: main()运行之后预期能看到这样一串输出先构建出含 4 个原子的 fcc 铜晶胞cubicTrue会生成常规立方胞然后优化几步能量大约在 -0.02 eV/atom 量级EMT 的绝对值本身没有物理意义只看相对变化最后在当前目录下生成runs/cu_final.xyz。如果要在真实场景里换成大模型Planner 需要实现同样的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 # 说明以下为调用思路示例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 ( 你是一个计算材料学助手。你只能通过提供的工具操作结构 不要凭空给出数值结果。每次只调用一个工具。 ) 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任务{task}\n当前状态{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 的工具调用回填格式不完全一样tool消息通常需要带tool_call_id。实际接入时请对照官方文档调整不要直接照抄。这也是本文故意把 Planner 抽成接口的原因——换个模型或者换个 SDK只需要改这一个文件。4.6 加入校验层前面说的校验层现在补上。它的作用是拦截那些看起来能跑但结果没意义的情况。# 文件路径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表示使用最小镜像约定对周期性体系这是必要的否则会误判跨边界的原子距离。这个检查在扩胞、切表面之后特别有用能抓出很多建模错误。把校验接进优化流程可以在optimize工具里返回值加一个validation字段也可以在循环层统一做。实践上更推荐在工具内部做因为工具知道自己的语义。5. 从演示走向生产扩展方向5.1 接入第一性原理计算与机器学习势演示用的是 EMT速度极快但没有精度。真实场景里通常要换成第一性原理计算器或机器学习势。ASE 的好处是接口统一只要计算器实现了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): 根据名称返回计算器实例。真实项目里在这里分支到 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})这里的关键设计是把计算器选择也变成一个参数让 Agent 可以在成本和质量之间做权衡。比如粗筛阶段用机器学习势最后精修用第一性原理。这种分阶段策略在真实项目里非常常见因为它能把计算成本降下来一大截。需要提醒的是真正的第一性原理计算动辄几十分钟到几小时Agent 的循环必须支持异步——不能让整个进程阻塞等待。实践做法是把任务提交到作业调度系统工具返回一个作业 ID然后另设一个查询工具轮询状态。这样 Agent 的循环节奏和计算任务的生命周期就解耦了。5.2 批量任务与结果汇总单个结构的优化只是起点。真实场景往往是几十上百个结构这时候 Agent 的角色就变成了调度员决定先跑哪些、哪些失败需要重试、哪些结果异常需要人工复核。批量场景下最重要的工程点是幂等性和缓存。每个结构用内容哈希做 key算过的直接读缓存不要重复算。这一步能省掉大量算力也能让整个流程可以断点续跑。结果汇总建议输出结构化格式JSON 或 CSV字段固定不要用自然语言描述结果。自然语言适合给模型读不适合给人做后续分析。5.3 让 Agent 输出可复现的记录一个容易被忽略的要求Agent 的每一次运行都应该产出一份可复现的记录包括任务描述、模型版本、工具调用序列、每个工具的输入输出、最终结果。这份记录的价值在于当结果出现争议时你可以一层层回溯到底是哪一步出了问题。实践上可以把前面循环里的trace直接序列化成 JSON 落盘文件名带上时间戳。如果接了真实模型建议把模型的原始响应也存下来方便排查是模型的问题还是解析的问题。6. 常见问题与排查清单6.1 高频问题对照表问题现象常见原因解决思路报错说某元素没有对应的 EMT 参数EMT 计算器只支持部分元素换用支持该元素的计算器或在工具层做元素白名单校验并提前返回明确错误优化跑完converged为 False初始结构离平衡位置太远、步数不够、判据过严先放宽 fmax 到 0.1 粗优化再收紧到 0.02 精优化或调整初始晶格常数能量出现nan或极大正值原子重叠、晶胞退化、计算器参数缺失用check_structure检查最小原子间距确认晶胞长度为正模型反复调用同一个工具工具返回值没有提供新信息模型无法判断进展检查工具返回是否包含关键数值在主循环加重复动作检测并返回提示工具调用报参数不匹配模型传了多余参数或类型不对在循环里捕获TypeError把错误信息回填给模型同时精简 schema 的 required 字段优化后晶格常数几乎没变用了固定晶胞的自由度设置只优化了原子位置明确是否需要优化晶胞ASE 中 BFGS 默认会优化所有自由度但需确认Atoms是否带正确的 pbc结果每次跑都不完全一样初始结构不同、优化器随机性、并行归约顺序固定初始结构来源、固定优化器参数、记录完整输入保存文件时报路径错误文件名包含路径分隔符或非法字符在工具层做文件名白名单校验只允许字母数字下划线和点6.2 建议的排查顺序遇到 Agent 跑飞的情况建议按这个顺序查先看 trace 里最后一个成功的工具调用是什么确认状态是否合法再看模型给出的参数是否在合理范围然后单独把那个工具函数拎出来脱离 Agent 手动调用一次确认计算本身没问题最后才怀疑模型。这个顺序能帮你快速区分计算问题和调度问题避免在错误的方向上浪费时间。一个很实用的技巧是准备一组固定的回归用例几个典型结构、几组典型参数每次改动 Agent 逻辑后跑一遍确认结果没变。Agent 系统的不确定性很强没有回归测试的话改一行代码可能带来完全意想不到的行为变化。7. 最佳实践与工程建议7.1 工具粒度的把握工具粒度是设计 Agent 时最需要反复调整的地方。太粗模型没有调度空间Agent 退化成一个固定脚本太细模型要在琐碎操作上消耗大量 token 和步数。一个经验法则是一个工具对应一个物理上有意义的操作。构建结构、优化结构、计算单点能、保存结构这些都是有明确物理含义的原子操作。而把第 3 个原子的 x 坐标加 0.1这种就不适合做成工具因为它不对应任何有意义的研究动作。另一个法则是如果一个操作几乎总是跟着另一个操作出现考虑把它们合并。比如优化并返回能量就比优化和读能量两个工具更实用因为分开调用只会增加步数。7.2 安全边界与资源控制涉及真实计算资源的场景安全边界必须提前设计。至少要有这几层文件写入限制在指定目录内计算任务有超时和资源上限单次会话的总计算量有配额危险操作比如删除文件、提交大规模作业需要显式确认。不要指望模型自己遵守这些规则。模型的输出是不可信的输入所有约束必须在代码层强制实施。这和 Web 开发里永远不要信任前端传参是同一个道理。7.3 可复现性与版本记录计算科学最讲究可复现。引入 Agent 之后可复现性面临新的挑战同一个任务模型可能给出不同的操作序列。应对办法有两个方向一是把所有输入任务描述、模型版本、温度参数、工具 schema 版本都记录下来二是关键流程提供固化能力也就是把一次成功的 Agent 运行固化成脚本后续直接跑脚本。第二个方向在实际项目中价值很高。Agent 负责探索一旦找到可行路径就固化成确定性流程既保留了灵活性又保证了稳定性。7.4 日志与可观测性建议给每次会话分配一个唯一 ID所有日志带上这个 ID。日志内容至少包括每步的动作名、参数、返回结果摘要、耗时。有了这些出问题时可以像查分布式系统调用链一样回溯。另外建议对工具调用做耗时统计。如果某个工具平均耗时特别长说明它可能被调用得过于频繁或者内部有优化空间。这类数据驱动的优化比凭感觉调整有效得多。7.5 成本控制如果接的是商用大模型 APItoken 成本需要关注。控制手段主要有三个精简 schema只保留必要工具和参数、精简状态摘要不要传完整结构、限制历史长度只保留最近若干轮对话。一个容易忽略的点是工具返回值的长度。如果工具返回了完整的坐标数组或者几千行的输出文件token 会瞬间爆掉。所有工具返回值都应该做摘要化处理只保留决策需要的数值。8. 学习路线与后续方向如果想把这条路走下去建议分三个阶段推进。第一阶段是把本文的演示跑通并且改造它。换几个不同的元素和晶体结构故意传入错误参数看系统怎么反应故意让优化不收敛看 Agent 能否自行调整。这个阶段的目的是建立对整个链路的直觉。第二阶段是接入真实计算。选一个你熟悉的小体系用你平时用的计算软件跑一遍然后把同样的流程用 Agent 封装。这个阶段会暴露大量工程细节问题作业提交、状态轮询、输出解析、错误恢复。把这些问题解决掉系统才算真正可用。第三阶段是做对比评估。用同一批任务分别用人工流程和 Agent 流程跑对比耗时、成本、结果一致性。只有在数据上站得住脚才值得推广。需要提前提醒的风险有几个。一是不要把 Agent 的输出当成最终结论所有数值结果都必须经过独立校验二是不要在未经验证的情况下让它操作生产计算资源三是注意数据的合规性涉及未公开材料的计算数据不要随意传给外部服务。最后想说Agent 在计算材料学里的定位短期内更像是熟练的科研助理而不是独立研究者。它能把重复劳动接过去能帮你把流程标准化能减少低级错误但科学判断的部分仍然需要人来把关。把这个定位想清楚落地的时候就不会有太多不切实际的期待也更容易做出真正有用的东西。
做计算化学和材料计算的朋友大多有过这样的体验一个结构优化的任务从建模、选泛函、设收敛标准、跑任务、看轨迹、判断是否收敛到最后一堆能量文件需要手工整理成表。整个链路里真正需要人做判断的环节其实只有几个剩下的全是重复劳动和格式转换。而偏偏这几个判断环节又强依赖经验新人很难独立完成。这篇文章想聊的就是能不能用 AI Agent 把这套链路串起来让模型负责决定下一步做什么让程序负责真正去做。文章会从概念讲起然后手写一个不依赖任何黑盒框架的最小 Agent用 ASE 内置的 EMT 计算器跑通建模—优化—校验—落盘的完整闭环最后再讨论怎么把这个玩具级实现扩展到真实的第一性原理计算和机器学习势场景。适合有 Python 基础、做过一些原子尺度模拟、想了解 Agent 工程化的读者。1. 为什么要把 AI Agent 引入计算化学与材料计算1.1 Agent 在这个语境下到底指什么先把这个词说清楚因为它在不同圈子里含义差别很大。在这里AI Agent 指的是一个由大语言模型驱动的决策循环模型读取当前的任务状态从一组预先定义好的工具里挑选一个调用拿到工具返回的结构化结果再决定下一步如此往复直到任务结束或者触发终止条件。它和用 ChatGPT 问一句然后复制粘贴结果有本质区别。后者模型只是一次性地产生文本所有执行动作由人完成前者模型处在一个闭环里它的每一次输出都会被程序解析成具体的函数调用执行结果又会回到模型的上下文里。换句话说Agent 的价值不在于模型懂多少化学而在于它能把意图翻译成操作序列并且根据中间结果动态调整。在计算化学和材料学里这个特性的用处非常明显。因为这类任务的本质是搜索——搜索构型空间、搜索参数组合、搜索收敛路径。人的经验本质上是一套启发式规则而 Agent 恰好可以把这套规则形式化成工具调用序列同时保留在遇到异常时改弦更张的能力。需要强调的是Agent 不是万能的。凡是需要高精度数值判断的地方比如某个泛函对某类体系的系统性误差模型基本给不出可靠结论。它的定位应该是实验记录员 操作员而不是理论家。1.2 与传统脚本、工作流引擎的区别很多人会问我写一个 Python 脚本把 ASE 的步骤串起来不就完了或者用工作流引擎编排一下这三者的差别值得掰开讲。传统脚本是确定性的路径写死。好处是可复现、易调试坏处是遇到边界情况就崩比如某个元素 EMT 不支持、某个晶格常数导致优化发散脚本没法自己绕过去只能人来改代码或者改参数。工作流引擎比如各种 DAG 编排工具解决了任务依赖和失败重试的问题但它的分支逻辑依然是人预先写死的。你可以配失败了重试三次但没法配如果能量异常升高就换个初始晶格常数再试。这类判断需要语义理解工作流引擎做不到。Agent 补的正是这一块把分支决策交给模型。代价是引入了不确定性——同样的输入模型两次可能给出不同的操作序列。所以在工程上一个靠谱的 Agent 系统必须有确定性的校验层兜底这一点后面会反复提到。一个实用的判断标准是如果你的任务流程完全固定、输入格式完全可控那就老老实实写脚本别上 Agent。如果你的任务需要看情况比如结构来源五花八门、收敛行为不可预测、需要根据中间结果选下一步那 Agent 才有发挥空间。1.3 计算材料学里适合 Agent 化的任务不是所有任务都值得 Agent 化。根据实际使用情况下面这几类收益比较明显。第一类是结构准备与预处理。从 CIF、POSCAR、SMILES 等各种来源读入结构判断晶胞是否合理、是否需要加真空层、是否需要扩胞、表面模型该切哪个晶面。这些判断规则性强但情况琐碎很适合交给 Agent 调度。第二类是计算流程编排。给定一个体系和一个目标比如算弹性常数或算形成能Agent 需要拆解成一系列计算任务决定顺序检查每一步的输出是否正常异常时调整参数重跑。第三类是结果解析与汇总。从大量输出文件里提取能量、力、带隙、晶格常数等量做单位换算整理成表格标注异常值。这类工作纯体力活Agent 做起来出错率反而比人低。第四类是文献与数据库的信息抽取辅助。比如从材料数据库批量拉取结构并做一致性检查。注意这里说的是辅助涉及判断的部分仍然需要人复核。反过来纯粹的精度评估、方法选择的理论论证、需要长期经验的误差分析这些不建议交给 Agent至少不能让它做最终决策。2. 环境准备与项目骨架2.1 运行环境与依赖说明本文示例以 Python 环境为例。Python 版本建议 3.9 以上因为代码里用了一些较新的类型标注写法from __future__ import annotations可以兼容低版本但为了少踩坑建议直接用较新的小版本。核心依赖只有两个方向计算侧和编排侧。计算侧本文用 ASEAtomic Simulation Environment它自带的 EMT 计算器可以对部分金属做快速近似计算正好适合做演示不需要安装任何第一性原理软件。编排侧如果要接真实大模型需要对应的 SDK如果只想先把流程跑通可以完全不用本文提供了一个离线的脚本化 Planner。需要说明的是具体依赖版本请以你本地环境的实际情况为准本文重点演示的是架构和配置思路不绑定某个特定版本号。安装命令大致如下# 建议在虚拟环境中操作 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 等常见元素的一部分。如果你的体系包含它不支持的元素跑起来会直接报错。这一点在演示阶段要特别注意后面常见问题一节会专门讲这个报错怎么排查。2.2 项目目录结构为了让代码可维护建议一开始就把结构分清楚。工具层负责真正干活Agent 层负责调度校验层负责兜底三者不要混在一个文件里。推荐的结构如下chem-agent/ ├── agent/ │ ├── __init__.py │ ├── session.py # 计算会话持有当前结构等状态 │ ├── tools.py # 工具函数实现 │ ├── schema.py # 工具描述给模型看的 │ ├── validators.py # 结果校验 │ └── loop.py # Agent 主循环 ├── planners/ │ ├── __init__.py │ ├── scripted.py # 离线规则 Planner用于测试 │ └── llm.py # 大模型 Planner可选 ├── runs/ # 运行产物自动创建 └── main.py # 入口这个划分的好处是计算逻辑tools.py完全不感知模型的存在可以被普通脚本直接调用也可以在 Agent 里被调用。这一点非常重要因为它意味着你的计算代码永远可以独立测试不会因为模型抽风而不可用。2.3 单位约定在动手写代码之前必须先把单位约定固定下来否则后面一定乱。ASE 内部统一使用 eV 作为能量单位、Å 作为长度单位、eV/Å 作为力的单位。工具函数的入参和返回值都遵循这套约定不要在中途混入 kcal/mol 或者 Hartree。如果最终要和其他软件对接单位换算放在结果输出环节统一做不要在工具内部做隐式转换。这个原则看似啰嗦但在实际项目里能省掉大量对不上数的排查时间。3. 核心原理拆解一个可落地的 Agent 由什么组成3.1 四要素模型抛开各种框架的包装一个能干活的计算 Agent 由四部分组成状态State、工具Tools、决策器Planner、循环控制器Loop Controller。状态是当前任务的全部上下文包括已构建的原子结构、已执行的操作历史、中间计算结果。在计算化学场景里状态管理是最容易被低估的部分。因为原子结构是个复杂对象没法直接塞进模型的上下文只能序列化成摘要信息元素组成、原子数、晶格参数、当前能量等传给模型。工具是一组有明确输入输出的函数。每个工具应该只做一件事并且可以被独立测试。工具设计得好不好直接决定了 Agent 的上限——模型再聪明如果工具粒度太粗比如一个工具直接跑完整套流程模型就没有调度空间如果太细比如一个工具只移动一个原子模型会被淹没在细节里。决策器负责根据当前状态选择下一步动作。它可以是规则脚本也可以是大模型。把它抽成接口的好处是开发阶段用规则脚本跑通流程上线前再换成模型两者可以随时切换对比。循环控制器负责防止 Agent 跑飞。必须有最大步数限制、重复动作检测、异常中断机制。一个没有终止条件的 Agent 是很危险的尤其是当工具会消耗真实计算资源的时候。3.2 工具契约设计的三条原则写工具函数的时候有三条原则值得坚持。第一条参数用基本类型。模型输出的参数是 JSON只能表达字符串、数字、布尔、数组、对象。所以工具参数不要设计成Atoms对象这种复杂类型而应该用symbolCu、a3.6这样的基本类型在函数内部再去构造对象。第二条返回值必须可序列化且有明确状态标识。建议统一返回一个 dict里面至少包含status字段ok/error和必要的数值结果。出错时不要抛异常穿透到循环层而是在工具内部捕获后返回{status: error, message: ...}。这样模型能看到错误信息并自行调整而不是整个程序崩掉。这点是 Agent 和普通脚本在设计理念上最大的不同之一。第三条单位写进描述里。工具的 description 字段里要明确写出参数和返回值的单位比如能量单位 eV、力收敛判据单位 eV/Å。模型对单位非常敏感描述里不写清楚它很容易传错量级。3.3 循环控制与终止条件一个最基本的 Agent 循环如下把当前状态和历史整理成消息列表。交给决策器得到下一个动作。如果是终止动作结束循环并输出结果。否则解析动作名和参数调用对应工具。记录工具返回结果回到第 1 步。这里面有几个必须设的护栏。最大步数限制比如 20 步防止无限循环重复动作检测防止模型卡在同一个调用上工具执行超时防止某个计算卡死异常动作工具名不存在、参数缺失要有明确的兜底返回而不是直接抛异常。在实际项目中还有一个容易被忽略的护栏状态一致性检查。比如模型调用了优化结构之后又调用了读取能量如果优化失败导致结构状态不合法读取能量就应该返回明确的错误而不是给出无意义的数值。3.4 校验层为什么不能省这一点值得单独强调。模型给出的操作序列在语义上可能是合理的但在数值上可能完全错误。比如它可能把晶格常数 3.6 写成 36或者把力的收敛判据 0.05 写成 5。这类错误如果直接传给计算程序轻则白跑一次重则产生一堆垃圾数据污染结果库。校验层的作用就是在工具执行前后做数值合理性检查晶格常数是否在合理区间比如 2 到 10 Å、原子间距是否过近小于 0.5 Å 通常意味建模出错、能量是否为有限值、优化后的最大力是否真的低于判据。这些检查写起来不复杂但能让整个系统的可靠性提升一个量级。后面实战部分会把它们具体实现出来。4. 完整实战搭建一个结构优化 Agent4.1 初始化项目与依赖先创建目录结构并写一个空的__init__.py然后在agent/session.py里定义会话对象。这个对象是整段代码的状态中心。# 文件路径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(当前会话还没有结构请先调用 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而且模型也看不懂坐标数组。摘要里给元素组成、原子数、晶格参数、当前能量已经足够支撑决策了。4.2 编写核心工具函数接下来是工具层。每个函数都遵循前面说的契约基本类型参数、dict 返回值、错误内部捕获。# 文件路径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]: 按指定晶格常数构建体相结构。a 的单位是 Å。 try: if not (2.0 float(a) 10.0): return { status: error, message: f晶格常数 {a} 不在合理区间 [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 做结构优化。fmax 单位 eV/Å。 try: atoms session.require_atoms() if not (1e-4 float(fmax) 1.0): return { status: error, message: f收敛判据 {fmax} eV/Å 不合理常见取值 0.01 ~ 0.1, } if not (1 int(steps) 2000): return {status: error, message: f步数 {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优化失败: {exc}} def get_state(session: ChemSession) - Dict[str, Any]: 读取当前会话状态摘要。 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()方法返回布尔值表示是否收敛这个返回值要透传给模型因为模型需要据此判断是继续调大步数还是调整初始结构。logfileos.devnull是为了避免优化过程刷屏实际项目中建议改成写文件方便事后复盘。最大力的计算用了(forces ** 2).sum(axis1).max() ** 0.5这是对每行三个分量求平方和再开方得到每个原子的力矢量模长取最大值。注意不要写成forces.max()那是对分量取最大物理意义完全不同。save_structure里对filename做了路径分隔符检查这是一个简单但必要的安全边界。如果不检查模型完全可能传入../../etc/passwd这种值。虽然这只是个演示项目但这种习惯要养成。4.3 注册工具 Schema工具写好了还要告诉模型有哪些工具、参数是什么。这里用标准的 function calling 格式组织。# 文件路径agent/schema.py TOOL_SCHEMA [ { type: function, function: { name: build_bulk, description: ( 按给定晶格常数构建体相晶体结构。 参数 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: 晶格常数单位 Å}, }, required: [symbol, a], }, }, }, { type: function, function: { name: optimize, description: 对当前结构做 BFGS 结构优化返回最终能量和最大力。, parameters: { type: object, properties: { fmax: { type: number, description: 力的收敛判据单位 eV/Å常用 0.05, }, steps: {type: integer, description: 最大优化步数}, }, required: [], }, }, }, { type: function, function: { name: get_state, description: 读取当前结构摘要包括组成、原子数、晶格常数、能量。, 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 是给模型看的写得好不好直接影响调用准确率。经验是把单位、常见取值、参数间的依赖关系都写进去模型出错的概率会明显下降。比如常见金属约在 3.0 到 4.5 之间这句话能有效避免模型传 36 这种量级错误。4.4 实现 Agent 主循环主循环负责把 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: 检测到连续重复调用请换一个动作} else: try: result self.tool_registry[name](**args) except TypeError as exc: result {status: error, message: f参数不匹配: {exc}} except Exception as exc: # noqa: BLE001 result {status: error, message: f工具执行异常: {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超过最大步数 {self.max_steps}, trace: self.trace}几个细节说明。tool_registry里用 lambda 把 session 闭包进去这样 Planner 只需要关心业务参数不需要处理 session。_is_repeat检测连续两次完全相同的调用这是最常见的卡死场景——模型看不到进展就一直重复同一个动作。TypeError单独捕获是因为参数不匹配在 Agent 场景里极其常见需要给模型明确的错误提示让它自我修正。另外注意返回值里带了完整trace这个在调试时非常有用可以看到模型每一步的原始决策。生产环境里应该把它写进日志文件而不是直接返回给用户。4.5 两个 Planner离线脚本与大模型先写一个离线的脚本化 Planner用于在不接大模型的情况下验证整条链路。# 文件路径planners/scripted.py from __future__ import annotations from typing import Any, Dict, List class ScriptedPlanner: 按预设脚本顺序返回动作用于离线联调和回归测试。 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: 脚本执行完毕}} 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 结构优化完成}}, ] def main() - None: session ChemSession(workdirruns) loop AgentLoop(session, ScriptedPlanner(SCRIPT)) result loop.run(task优化 fcc Cu 的晶格常数) for item in result.get(trace, []): print(item) if __name__ __main__: main()运行之后预期能看到这样一串输出先构建出含 4 个原子的 fcc 铜晶胞cubicTrue会生成常规立方胞然后优化几步能量大约在 -0.02 eV/atom 量级EMT 的绝对值本身没有物理意义只看相对变化最后在当前目录下生成runs/cu_final.xyz。如果要在真实场景里换成大模型Planner 需要实现同样的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 # 说明以下为调用思路示例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 ( 你是一个计算材料学助手。你只能通过提供的工具操作结构 不要凭空给出数值结果。每次只调用一个工具。 ) 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任务{task}\n当前状态{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 的工具调用回填格式不完全一样tool消息通常需要带tool_call_id。实际接入时请对照官方文档调整不要直接照抄。这也是本文故意把 Planner 抽成接口的原因——换个模型或者换个 SDK只需要改这一个文件。4.6 加入校验层前面说的校验层现在补上。它的作用是拦截那些看起来能跑但结果没意义的情况。# 文件路径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表示使用最小镜像约定对周期性体系这是必要的否则会误判跨边界的原子距离。这个检查在扩胞、切表面之后特别有用能抓出很多建模错误。把校验接进优化流程可以在optimize工具里返回值加一个validation字段也可以在循环层统一做。实践上更推荐在工具内部做因为工具知道自己的语义。5. 从演示走向生产扩展方向5.1 接入第一性原理计算与机器学习势演示用的是 EMT速度极快但没有精度。真实场景里通常要换成第一性原理计算器或机器学习势。ASE 的好处是接口统一只要计算器实现了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): 根据名称返回计算器实例。真实项目里在这里分支到 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})这里的关键设计是把计算器选择也变成一个参数让 Agent 可以在成本和质量之间做权衡。比如粗筛阶段用机器学习势最后精修用第一性原理。这种分阶段策略在真实项目里非常常见因为它能把计算成本降下来一大截。需要提醒的是真正的第一性原理计算动辄几十分钟到几小时Agent 的循环必须支持异步——不能让整个进程阻塞等待。实践做法是把任务提交到作业调度系统工具返回一个作业 ID然后另设一个查询工具轮询状态。这样 Agent 的循环节奏和计算任务的生命周期就解耦了。5.2 批量任务与结果汇总单个结构的优化只是起点。真实场景往往是几十上百个结构这时候 Agent 的角色就变成了调度员决定先跑哪些、哪些失败需要重试、哪些结果异常需要人工复核。批量场景下最重要的工程点是幂等性和缓存。每个结构用内容哈希做 key算过的直接读缓存不要重复算。这一步能省掉大量算力也能让整个流程可以断点续跑。结果汇总建议输出结构化格式JSON 或 CSV字段固定不要用自然语言描述结果。自然语言适合给模型读不适合给人做后续分析。5.3 让 Agent 输出可复现的记录一个容易被忽略的要求Agent 的每一次运行都应该产出一份可复现的记录包括任务描述、模型版本、工具调用序列、每个工具的输入输出、最终结果。这份记录的价值在于当结果出现争议时你可以一层层回溯到底是哪一步出了问题。实践上可以把前面循环里的trace直接序列化成 JSON 落盘文件名带上时间戳。如果接了真实模型建议把模型的原始响应也存下来方便排查是模型的问题还是解析的问题。6. 常见问题与排查清单6.1 高频问题对照表问题现象常见原因解决思路报错说某元素没有对应的 EMT 参数EMT 计算器只支持部分元素换用支持该元素的计算器或在工具层做元素白名单校验并提前返回明确错误优化跑完converged为 False初始结构离平衡位置太远、步数不够、判据过严先放宽 fmax 到 0.1 粗优化再收紧到 0.02 精优化或调整初始晶格常数能量出现nan或极大正值原子重叠、晶胞退化、计算器参数缺失用check_structure检查最小原子间距确认晶胞长度为正模型反复调用同一个工具工具返回值没有提供新信息模型无法判断进展检查工具返回是否包含关键数值在主循环加重复动作检测并返回提示工具调用报参数不匹配模型传了多余参数或类型不对在循环里捕获TypeError把错误信息回填给模型同时精简 schema 的 required 字段优化后晶格常数几乎没变用了固定晶胞的自由度设置只优化了原子位置明确是否需要优化晶胞ASE 中 BFGS 默认会优化所有自由度但需确认Atoms是否带正确的 pbc结果每次跑都不完全一样初始结构不同、优化器随机性、并行归约顺序固定初始结构来源、固定优化器参数、记录完整输入保存文件时报路径错误文件名包含路径分隔符或非法字符在工具层做文件名白名单校验只允许字母数字下划线和点6.2 建议的排查顺序遇到 Agent 跑飞的情况建议按这个顺序查先看 trace 里最后一个成功的工具调用是什么确认状态是否合法再看模型给出的参数是否在合理范围然后单独把那个工具函数拎出来脱离 Agent 手动调用一次确认计算本身没问题最后才怀疑模型。这个顺序能帮你快速区分计算问题和调度问题避免在错误的方向上浪费时间。一个很实用的技巧是准备一组固定的回归用例几个典型结构、几组典型参数每次改动 Agent 逻辑后跑一遍确认结果没变。Agent 系统的不确定性很强没有回归测试的话改一行代码可能带来完全意想不到的行为变化。7. 最佳实践与工程建议7.1 工具粒度的把握工具粒度是设计 Agent 时最需要反复调整的地方。太粗模型没有调度空间Agent 退化成一个固定脚本太细模型要在琐碎操作上消耗大量 token 和步数。一个经验法则是一个工具对应一个物理上有意义的操作。构建结构、优化结构、计算单点能、保存结构这些都是有明确物理含义的原子操作。而把第 3 个原子的 x 坐标加 0.1这种就不适合做成工具因为它不对应任何有意义的研究动作。另一个法则是如果一个操作几乎总是跟着另一个操作出现考虑把它们合并。比如优化并返回能量就比优化和读能量两个工具更实用因为分开调用只会增加步数。7.2 安全边界与资源控制涉及真实计算资源的场景安全边界必须提前设计。至少要有这几层文件写入限制在指定目录内计算任务有超时和资源上限单次会话的总计算量有配额危险操作比如删除文件、提交大规模作业需要显式确认。不要指望模型自己遵守这些规则。模型的输出是不可信的输入所有约束必须在代码层强制实施。这和 Web 开发里永远不要信任前端传参是同一个道理。7.3 可复现性与版本记录计算科学最讲究可复现。引入 Agent 之后可复现性面临新的挑战同一个任务模型可能给出不同的操作序列。应对办法有两个方向一是把所有输入任务描述、模型版本、温度参数、工具 schema 版本都记录下来二是关键流程提供固化能力也就是把一次成功的 Agent 运行固化成脚本后续直接跑脚本。第二个方向在实际项目中价值很高。Agent 负责探索一旦找到可行路径就固化成确定性流程既保留了灵活性又保证了稳定性。7.4 日志与可观测性建议给每次会话分配一个唯一 ID所有日志带上这个 ID。日志内容至少包括每步的动作名、参数、返回结果摘要、耗时。有了这些出问题时可以像查分布式系统调用链一样回溯。另外建议对工具调用做耗时统计。如果某个工具平均耗时特别长说明它可能被调用得过于频繁或者内部有优化空间。这类数据驱动的优化比凭感觉调整有效得多。7.5 成本控制如果接的是商用大模型 APItoken 成本需要关注。控制手段主要有三个精简 schema只保留必要工具和参数、精简状态摘要不要传完整结构、限制历史长度只保留最近若干轮对话。一个容易忽略的点是工具返回值的长度。如果工具返回了完整的坐标数组或者几千行的输出文件token 会瞬间爆掉。所有工具返回值都应该做摘要化处理只保留决策需要的数值。8. 学习路线与后续方向如果想把这条路走下去建议分三个阶段推进。第一阶段是把本文的演示跑通并且改造它。换几个不同的元素和晶体结构故意传入错误参数看系统怎么反应故意让优化不收敛看 Agent 能否自行调整。这个阶段的目的是建立对整个链路的直觉。第二阶段是接入真实计算。选一个你熟悉的小体系用你平时用的计算软件跑一遍然后把同样的流程用 Agent 封装。这个阶段会暴露大量工程细节问题作业提交、状态轮询、输出解析、错误恢复。把这些问题解决掉系统才算真正可用。第三阶段是做对比评估。用同一批任务分别用人工流程和 Agent 流程跑对比耗时、成本、结果一致性。只有在数据上站得住脚才值得推广。需要提前提醒的风险有几个。一是不要把 Agent 的输出当成最终结论所有数值结果都必须经过独立校验二是不要在未经验证的情况下让它操作生产计算资源三是注意数据的合规性涉及未公开材料的计算数据不要随意传给外部服务。最后想说Agent 在计算材料学里的定位短期内更像是熟练的科研助理而不是独立研究者。它能把重复劳动接过去能帮你把流程标准化能减少低级错误但科学判断的部分仍然需要人来把关。把这个定位想清楚落地的时候就不会有太多不切实际的期待也更容易做出真正有用的东西。
