让 Agent 用代码行动：Hugging Face smolagents 的轻量实践

最近在做 Agent 原型时，我重新思考了一个问题：模型到底应该输出一段结构化 JSON，还是直接写出下一步动作的代码？Hugging Face 在 smolagents 介绍中给出的答案很有启发性——让代码成为动作表达层，再由受控运行环境执行它。本文把这条思路改写成几个可落地的工程判断。

一、先判断是否真的需要 Agent
如果需求可以稳定拆成固定分支，例如“选择套餐后查询知识库”或“提交表单后通知负责人”，确定性流程更可靠，也更容易测试。只有当用户输入变化大、步骤需要动态选择，或者工具组合无法预先穷举时，才值得引入 Agent。

二、代码动作为什么更灵活
代码天然支持组合、变量和循环。一个动作的结果可以赋给变量，后续动作继续使用；常用步骤也能封装成函数。相比把工具名和参数塞进 JSON，代码更接近真实程序，模型更容易表达多步计划。smolagents 因此把核心抽象保持得很小，并把 CodeAgent 作为一等能力。

三、给代码执行加边界
代码代理并不等于无限权限。实践中应把工具白名单、网络访问、文件范围和运行时长写成明确策略；高风险操作放进沙箱，执行结果回传后再决定下一步。保留完整轨迹，才能复盘错误动作并做回归测试。

四、一个轻量落地路径
先用普通函数实现工具，再让模型只负责选择工具和组织顺序；确认收益后，再开放有限的代码动作。每增加一种自主性，都补一条失败用例和观测指标，例如工具成功率、重试次数和最终任务完成率。

结语
smolagents 的价值不在于“让模型写更多代码”，而在于用很薄的抽象把行动表达、工具调用和安全边界连接起来。对小型 Agent 来说，先保持简单、可追踪，再逐步增加自主性，往往比堆叠复杂框架更稳妥。

来源：Hugging Face 官方文章《Introducing smolagents, a simple library to build agents》
https://huggingface.co/blog/smolagents