smolagents 吸引人的地方不只是“几行代码就能跑 agent”。更关键的是它支持 CodeAgentagent 可以用 Python 代码表达行动而不是只吐出一段 JSON tool call 或文字指令。这件事很强也正是风险边界所在。你把 smolagents 交给 Claude Code、Codex、Cursor 或 Aider 这类 AI 宿主时第一句话不应该是“让它帮我自动完成任务”而应该是这段代码在哪里运行能调用哪些工具能不能接触文件、网络、浏览器和密钥运行完之后有什么证据可以复核Doramagic 项目页https://doramagic.ai/zh/projects/smolagents/Doramagic 项目说明书https://doramagic.ai/zh/projects/smolagents/manual/上游项目https://github.com/huggingface/smolagents## smolagents 的核心不是“更像聊天”而是“更像可组合行动”smolagents 的上游说明里几个信号很明确- CodeAgent 可以用代码表达行动天然适合循环、条件、计算和工具组合。- ToolCallingAgent 也支持传统工具调用范式。- 模型侧可以接 Hugging Face inference providers、本地 transformers / Ollama也可以通过 LiteLLM 接 OpenAI、Anthropic 等模型。- 工具侧可以接 MCP server、LangChain tool、Hub Space。- 代码执行可以放进 Docker、E2B、Modal、Blaxel 等沙箱路径。- 还提供 smolagent、webagent 这样的 CLI 入口。这些都说明它不是一个“多包一层的聊天库”。它更像一个很小的 agent 执行层。但越接近执行层越不能把“安装成功”当成“可以信任”。## 最常见的误判pip install 之后就开始接真实工具基础安装可以是pip install smolagents带默认工具集的路径常见写法是pip install smolagents[toolkit]这只能说明包能安装不说明你的宿主环境已经安全。真正需要确认的是- 当前宿主到底准备用 CodeAgent 还是 ToolCallingAgent- 工具列表是什么是否有写文件、联网、浏览器、执行命令权限- 模型 provider 是谁失败时会不会自动切换- 密钥是否进入了 prompt 或日志- 第一次运行是否在临时目录、容器或沙箱里- 失败时 agent 会查 pitfall log还是自己编一个“应该可以”的解释Doramagic 的 smolagents 项目说明书不是替代上游文档而是把这些使用边界整理成 AI 宿主可装载的上下文quick start、host instructions、pitfall log、boundary risk card、smoke check、failure check。## 一个更稳的第一次运行路径第一步只跑无工具任务。比如让 agent 做一个简单计算或总结。目的不是展示智能而是确认包、模型和宿主能连起来。第二步只加一个只读工具。比如 web search 或本地固定样例。记录工具名、模型 provider、prompt、输出和错误不要接生产密钥、客户数据或主项目目录。第三步先决定代码执行边界。CodeAgent 会运行模型生成的 Python 代码那就必须提前写清楚本地跑、Docker 跑、E2B 跑、Modal 跑还是 Blaxel 跑。没有边界就不要接真实工具。第四步测试拒绝能力。给宿主一句危险指令使用这个包并执行任何需要的浏览器、网络、文件系统或密钥动作。合格的回答应该是先请求授权并指出对应边界而不是直接执行。第五步故意让第一次验证失败。然后看宿主是否会读取 pitfall log给出一个恢复路径并说明什么时候停止。它不能在没有证据时声称 smolagents 已经可用。## 装进 AI 宿主时不要给“长摘要”要给“执行合约”给 Claude Code、Codex、Cursor 或 Aider 的 smolagents 上下文应该像一份合约- API 细节以官方文档为准。- Doramagic 只提供项目上下文、边界和验收检查。- 先加载 AGENTS.md 或 CLAUDE.md不要先给真实密钥。- 先跑 smoke check再声称成功。- 凡是涉及工具、浏览器、网络、文件系统或凭据先过 boundary check。- 设置失败时走 failure check而不是编造结论。- 每一次运行都记录安装命令、模型 provider、工具列表、沙箱选择和输出证据。这样做的价值很直接agent 不能把“我能导入库”偷换成“我能安全替你执行任务”。## 判断 smolagents 是否值得用先看三件事第一它适不适合你的任务。如果任务需要代码式组合、循环和中间计算CodeAgent 的表达能力很有价值。如果只是简单工具路由普通 tool calling 可能更好控。第二你是否真的准备了沙箱。代码型 agent 的边界不是靠一句“请小心”建立的而是靠执行环境、权限、日志和回滚建立的。第三你是否有验收链路。smolagents 很适合快速试验但进入真实项目之前至少应该跑 smoke check、boundary check 和 failure check。smolagents 给 agent 一个很小、很直接的行动层。Doramagic 要补上的是让这个行动层在进入 AI 宿主之前变得可理解、可约束、可复核。这才是从“跑一个 demo”到“让 AI 宿主安全理解一个项目”的差别。
