Atomic Forge 实战指南：为 Atomic Agents 下载、集成与打造自定义 Atomic Tool

• AI Agent
• Agent 框架
• MCP 服务
• 后端

Atomic Forge 是 Atomic Agents 生态中的可下载工具集合，与核心库atomic-agents、CLIatomic-assembler一起组成 monorepo 的四大模块（详见主 README）。它不是可pip install的独立包，而是一组"下载到你的项目里即用"的原子化组件——每个工具都是一个自包含、可独立运行、也可被 Agent 直接调用的 Python 模块。读完本文，你将掌握：Atomic Forge 为何采用"可下载而非打包"的设计哲学、14 个开箱即用工具分别能做什么、如何通过 Atomic Assembler CLI 或手动复制将工具接入自己的项目，以及如何遵循框架规范从零打造一个自定义 Atomic Tool（完整代码示例 + 源码级原理分析）。

Atomic Forge 是什么：一个"可下载工具"的集合而非软件包

Atomic Forge 的定位在 atomic-forge/README.md 中写得很明确：它是一组可与 Atomic Agents 配合使用的工具集合，用于扩展框架功能、对接第三方服务。仓库里每一款工具都有独立的目录、自己的pyproject.toml、README、依赖声明和测试用例。

值得强调的是官方刻意强调的设计决策——Atomic Forge 不是一个 package，而是一个"可下载工具的文件夹"。初看有些反直觉，但官方列出了三点理由，恰好也是这套方案的价值所在：

1. 完全掌控（Full Control）：下载到本地后，每个工具的所有权完全属于你。喜欢某个搜索工具但希望按自己的方式排序结果？直接改，不会影响其他使用者；当然，如果你的改进对别人也有价值，也欢迎向 Atomic Forge 仓库提交 Pull Request。
2. 依赖管理（Dependency Management）：工具一旦下载就位于你自己的代码库中，依赖的引入、升级、冲突排查都由你自主掌控。
3. 轻量（Lightweight）：每个工具都是独立组件，你可以只下载真正需要的工具，而不是让项目被一堆无关依赖撑大——正如官方举例所说："如果你不用 Calculator 工具，就没必要让项目背上 Sympy 这个依赖。"

这种"复制进你的代码库"的交付方式，与传统的"库依赖"模式形成鲜明对比：不是引入一个巨大的 SDK，而是把恰好你需要的那一个能力搬进项目，并保留完全改造的自由度。

工具清单：14 个开箱即用的原子能力

Atomic Forge 目前收录了 14 个工具，全部位于 atomic-forge/tools 目录下，每个工具目录内都包含独立的tool/源码目录、tests/测试目录、README.md和pyproject.toml：

从列表中可以看出几个共性：多数工具调用免费公共 API（arXiv、Hacker News/Algolia、Open-Meteo、Wikipedia），无需 API key 即可上手；需要密钥的工具（Tavily、Serply、BoCha）也全部支持从环境变量读取。仓库中的 web-search-agent、deep-research、youtube-summarizer 等示例项目正是基于这些工具搭建的真实应用，可以直接作为集成参考。

获取工具：Atomic Assembler CLI 与手动复制两种方式

方式一：使用 Atomic Assembler CLI（推荐）

Atomic Agents 附带一个名为Atomic Assembler的命令行工具，专门用于管理、下载 Tools。在安装atomic-agents后（pip install atomic-agents，详见主 README），直接运行：

atomic

如果你是从克隆仓库通过 uv 运行，则使用：

uv run atomic

启动后会出现交互式菜单，从工具列表中选择你要下载的工具，随后 CLI 会询问目标目录，将完整的工具目录（含tool/源码、tests/测试、README 与工程配置）下载到指定位置。每个工具在菜单中都带有自己的输入/输出 schema、使用示例、依赖清单和安装说明，方便你在下载前判断是否合适。

CLI 的完整实现在 atomic-assembler 目录中，其交互界面基于rich构建：app.py承载应用主流程，screens/main_menu.py提供工具选择菜单，screens/atomic_tool_explorer.py与widgets/tool_info_display.py负责展示工具详情，下载后你可以直接阅读这些源码了解 CLI 的内部逻辑。

方式二：手动复制（Copy/Paste）

如果你更喜欢零依赖的接入方式，官方也完全支持"传统手工"路线：直接把工具源码从仓库复制进自己的项目。例如把某个工具的tool/文件夹连同测试一起拷贝到你的代码库中，前提是项目已按主 README 的说明安装好atomic-agents。每个工具都是自包含模块，复制后即可import使用。

从源码结构看，两种方式最终殊途同归：工具以目录形式落地你的项目，tool/下的模块被你的代码直接导入，而不再通过包管理器间接引用。

解析一个真实工具：Calculator 的源码级解剖

为了理解"原子工具"长什么样，我们从实现最简单也最能说明问题的Calculator入手，逐段阅读 tool/calculator.py 的完整实现。它只有约 100 行，却完整体现了 Atomic Tool 的全部要素。

输入输出 Schema：继承BaseIOSchema

from pydantic import Field from sympy import sympify from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig ################ # INPUT SCHEMA # ################ class CalculatorToolInputSchema(BaseIOSchema): """ Tool for performing calculations. Supports basic arithmetic operations like addition, subtraction, multiplication, and division, as well as more complex operations like exponentiation and trigonometric functions. Use this tool to evaluate mathematical expressions. """ expression: str = Field(..., description="Mathematical expression to evaluate. For example, '2 + 2'.") ################# # OUTPUT SCHEMA # ################# class CalculatorToolOutputSchema(BaseIOSchema): """Schema for the output of the CalculatorTool.""" result: str = Field(..., description="Result of the calculation.")

输入 schema 只有一个expression字符串字段，输出 schema 只有一个result字符串字段。这里有几个值得注意的框架级细节：

• docstring 即 description。查看 base_io_schema.py 可以看到BaseIOSchema在__pydantic_init_subclass__中强制校验类必须有非空 docstring，否则直接抛出ValueError。这是因为 schema 类的 docstring 会被model_json_schema()提取为 JSON Schema 的description，最终作为给 LLM 看的工具说明注入提示词。
• 无副作用的设计：BaseIOSchema继承自 Pydantic 的BaseModel，天然获得类型校验、默认值、JSON 序列化能力；__str__返回model_dump_json()，与rich集成后还能在终端里漂亮地打印。

配置类：继承BaseToolConfig

################# # CONFIGURATION # ################# class CalculatorToolConfig(BaseToolConfig): safe_mode: bool = True allowed_functions: Dict[str, Any] = {}

BaseToolConfig在 base_tool.py 中定义，自带两个可选字段title和description，用于覆盖工具默认的标题与描述。Calculator 在此基础上新增了safe_mode与allowed_functions两个安全相关的配置项。

主工具类：继承BaseTool并实现run

##################### # MAIN TOOL & LOGIC # ##################### class CalculatorTool(BaseTool[CalculatorToolInputSchema, CalculatorToolOutputSchema]): def __init__(self, config: CalculatorToolConfig = CalculatorToolConfig()): super().__init__(config) self.safe_mode = config.safe_mode self.allowed_functions = config.allowed_functions def run(self, params: CalculatorToolInputSchema) -> CalculatorToolOutputSchema: # Convert the expression string to a symbolic expression parsed_expr = sympify(str(params.expression)) # Evaluate the expression numerically result = parsed_expr.evalf() return CalculatorToolOutputSchema(result=str(result))

关键点：

• 泛型参数即协议契约：BaseTool[InputSchema, OutputSchema]的两个类型参数声明了工具的输入输出协议。查看 base_tool.py 可以看到，BaseTool.__init_subclass__会捕获泛型实参存入_input_schema_cls/_output_schema_cls，并据此提供input_schema、output_schema两个类属性。input_schema的类名和 docstring 会通过model_json_schema()生成工具名与工具描述——这也是"用配置覆盖标题/描述"的机制来源。
• run是强制入口：BaseTool.run是抽象方法（base_tool.py），任何子类都必须实现它。这是 Agent 调用工具的统一入口。

用法示例与测试

Calculator 自带if __name__ == "__main__"演示块，直接运行模块即可验证：

if __name__ == "__main__": calculator = CalculatorTool() result = calculator.run(CalculatorToolInputSchema(expression="sin(pi/2) + cos(pi/4)")) print(result) # Expected output: {"result":"1.70710678118655"}

仓库为每个工具都配备了自动化测试，Calculator 的测试在 test_calculator.py 中：

def test_calculator_tool(): calculator_tool = CalculatorTool() input_schema = CalculatorToolInputSchema(expression="2 + 2") result = calculator_tool.run(input_schema) assert result == CalculatorToolOutputSchema(result="4.00000000000000")

这个测试同时验证了两件事：计算结果正确，以及返回对象是严格的CalculatorToolOutputSchema实例（而非普通 dict），这正是框架强调"结构化输出"的体现。

用多工具组合理解"可插拔"设计

单独看 Calculator 可能觉得简单，但把它放进 Agent 工作流里，"可插拔"的价值就显现了。以 deep-research 示例为例，其中的 Decider Agent 会判断用户问题，把任务路由给使用不同工具的搜索型 Agent——而 web-search-agent 中的SearXNGSearchTool则展示了另一种复杂度更高的真实工具形态。

以 Tavily Search 为例，它的配置更丰富，完整源码在 tool/tavily_search.py：

class TavilySearchToolConfig(BaseToolConfig): api_key: str = "" max_results: int = 5 search_depth: Literal["basic", "advanced"] = "basic" include_domains: Optional[List[str]] = None exclude_domains: Optional[List[str]] = None

其输入queries是一个字符串列表，输出results是TavilySearchResultItemSchema列表（含title、url、content、score、raw_content、query、answer等字段）。实现上它用aiohttp并发请求多个查询，再用ThreadPoolExecutor包装异步逻辑以提供同步的run()接口——从源码看，同步run内部是通过在线程池中运行asyncio.run实现的。这告诉我们一个规律：真实工具的复杂度差异很大，但对外契约永远是"配置类 + 输入 schema + 输出 schema +run()"这四个稳定接口。

因此，在不同搜索工具之间切换异常简单：只要输入输出 schema 对齐，把 Agent 里的工具实例换掉即可。这正是 Atomic Agents 主 README 强调的"Chaining Schemas and Agents"模式（见主 README）。

创建自定义 Atomic Tool：完整实战指南

Atomic Forge 不仅提供现成工具，更把"如何写一个新工具"沉淀为一份完整的规范指南：atomic-forge/guides/tool_structure.md。下面以指南中的Pizza Ordering Tool（披萨下单工具）为贯穿示例，完整还原六段式标准结构的每个环节。

设计原则：一个原子工具应该是什么样

任何 Atomic Tool 都应自包含、模块化：它封装一项具体功能（计算器、字幕抓取器或披萨下单服务），既能独立运行，也能被 AI Agent 调用。官方对工具的六条要求是：

• 单一职责：专注于一项具体任务；
• 模块化、可复用：可轻松集成到不同 Agent 或应用中；
• 自包含：包含独立运行所需的全部组件；
• 接口清晰：定义明确的输入/输出 schema，保证数据一致性；
• 可配置：通过配置项允许自定义，而非硬编码；
• 可独立执行：既能独立运行，也能作为 Atomic Agent 的一部分。

工程结构：一个工具 = 一个目录

每个工具应放在独立文件夹中，标准布局如下（对照 atomic-forge/tools/calculator 可看到完全一致的真实结构）：

tool_name/ │ .coveragerc │ pyproject.toml │ README.md │ requirements.txt │ uv.lock │ ├── tool/ │ │ tool_name.py │ │ some_util_file.py │ │ another_util_file.py │ └── tests/ │ test_tool_name.py │ test_some_util_file.py │ test_another_util_file.py

各文件职责：

• pyproject.toml：Python 项目元数据与依赖声明，由 uv 管理。开发前务必先运行uv sync，以获得干净、独立的环境。
• README.md：工具说明文档，包含用途、使用方法、环境变量等，可参考现有工具的 README 撰写。
• requirements.txt：仅列出运行时依赖，必须与pyproject.toml中的非开发依赖完全一致（排除python版本声明）。官方强调要手动创建这个文件，确保它干净、只含必要运行时依赖。
• .coveragerc：覆盖率工具配置，所有工具通用，必须包含。
• uv.lock：上次执行uv sync时安装的确切依赖版本锁文件，应提交到仓库以保证跨环境依赖一致。

pyproject.toml与requirements.txt的正确姿势

指南给出了一个披萨工具的pyproject.toml示例：

[build-system] requires = ["hatchling"] build-backend = "hatchling.build" [project] name = "pizza-ordering-tool" version = "1.0.0" description = "A tool for placing and processing pizza orders" readme = "README.md" requires-python = ">=3.12" dependencies = [ "atomic-agents", "pydantic>=2.8.2,<3.0.0", "requests>=2.28.0,<3.0.0", ] [dependency-groups] dev = [ "coverage>=7.0.0,<8.0.0", "pytest>=8.0.0,<9.0.0", "pytest-cov>=5.0.0,<6.0.0", "python-dotenv>=1.0.0,<2.0.0", "rich>=13.7.0,<14.0.0", ] [tool.uv.sources] atomic-agents = { workspace = true }

对应的requirements.txt只保留运行时依赖：

atomic-agents>=1.0.0,<2.0.0 pydantic>=2.8.2,<3.0.0 requests>=2.28.0,<3.0.0

三点纪律需要记住：requirements.txt只含[project.dependencies]中的包；绝不能包含[dependency-groups.dev]下的开发依赖；手写而非自动生成。真实工具与指南完全一致，例如 calculator 的 pyproject.toml 声明requires-python = ">=3.12"与sympy>=1.12,<2.0.0等运行时依赖。

继承规则：三类基类缺一不可

为保证框架内的一致性，你的工具类必须严格继承对应基类：

遵守这套继承规则，工具才能与框架其他组件无缝集成。需要特别说明的是BaseToolConfig的title/description覆盖能力（base_tool.py）：默认情况下工具名取自输入 schema 的 title、工具描述取自 schema docstring；但某些边界场景需要手动覆盖——例如一个工具做网页搜索、另一个在内部文档向量库中检索，你可能希望让 LLM 在回答公司内部问题时优先调用向量检索工具而不是网页搜索工具，此时通过配置覆盖描述就是最直接的手段。

六段式标准结构

指南明确规定，一个 Atomic Tool 的源码应严格按以下顺序组织，每个 section（除 imports 外）用包含 section 名的注释块明确分隔：

1. Imports（导入）
2. Input Schema（输入 Schema）
3. Output Schema(s)（输出 Schema，可有多个）
4. Configuration（配置）
5. Main Tool & Logic（主工具与逻辑）
6. Example Usage（示例用法）

注释块的标准写法例如：

################ # Input Schema # ################

下面完整走一遍 Pizza 示例。

① Imports：标准库、第三方包、Atomic Agents 框架模块统一放在文件顶部：

import os from enum import Enum from typing import List, Optional from pydantic import BaseModel, Field from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig

② Input Schema：用 Pydantic 模型定义输入结构与校验规则，支持枚举和嵌套模型组合成复杂输入：

################ # Input Schema # ################ class PizzaSize(Enum): SMALL = "Small" MEDIUM = "Medium" LARGE = "Large" class CrustType(Enum): THIN = "Thin" THICK = "Thick" STUFFED = "Stuffed" class Topping(BaseModel): name: str = Field(..., description="Name of the topping.") extra_cheese: bool = Field(False, description="Add extra cheese to this topping.") class PizzaOrderInputSchema(BaseIOSchema): """ Captures customer details and order specifics for placing a pizza order. """ customer_name: str = Field(..., description="Name of the customer placing the order.") pizza_type: str = Field(..., description="Type of pizza to order (e.g., Margherita, Pepperoni).") size: PizzaSize = Field(..., description="Size of the pizza.") crust: CrustType = Field(..., description="Type of crust for the pizza.") toppings: Optional[List[Topping]] = Field(None, description="List of additional toppings.") quantity: int = Field(..., description="Number of pizzas to order.")

要点：枚举限制合法取值；Topping是独立 Pydantic 模型并嵌套进主 schema；每个字段用Field(..., description=...)提供说明；主 schema 继承BaseIOSchema。

③ Output Schema(s)：定义工具产出的数据结构，一个工具可以有多个输出 schema：

##################### # Output Schema(s) # ##################### class OrderStatus(Enum): PENDING = "Pending" CONFIRMED = "Confirmed" DELIVERED = "Delivered" class OrderConfirmationSchema(BaseIOSchema): """ Confirmation details of the placed order. """ order_id: str = Field(..., description="Unique identifier for the order.") estimated_delivery_time: str = Field(..., description="Estimated time for order delivery.") status: OrderStatus = Field(..., description="Current status of the order.") class PaymentDetailsSchema(BaseIOSchema): """ Payment information for the order. """ amount: float = Field(..., description="Total amount to be paid.") currency: str = Field("USD", description="Currency of the payment.") payment_status: str = Field(..., description="Status of the payment (e.g., Paid, Pending).")

订单确认与支付信息拆成两个独立 schema，同样都继承BaseIOSchema。

④ Configuration：通过配置类开放自定义行为，敏感信息（如 API key）从环境变量读取：

################# # Configuration # ################# class PizzaOrderingToolConfig(BaseToolConfig): """ Configuration for the PizzaOrderingTool. """ api_endpoint: str = Field( default="https://api.pizzaorders.com/v1/orders", description="API endpoint for processing pizza orders." ) supported_pizzas: List[str] = Field( default=["Margherita", "Pepperoni", "Veggie", "Hawaiian"], description="List of supported pizza types." ) api_key: str = Field( default=os.getenv("PIZZA_API_KEY"), description="API key for authenticating with the pizza ordering service." ) title: Optional[str] = Field( default="Pizza Ordering Tool", description="Override the default title of the tool." ) description: Optional[str] = Field( default="A tool to place pizza orders and process payments.", description="Override the default description of the tool." )

⑤ Main Tool & Logic：实现核心业务逻辑。工具必须有run方法作为执行入口；用继承自BaseTool的泛型参数声明输入输出协议；复杂逻辑拆分为小方法；对非法输入做校验并抛出异常：

##################### # Main Tool & Logic # ##################### class PizzaOrderingTool(BaseTool[PizzaOrderInputSchema, OrderConfirmationSchema]): """ Tool for placing pizza orders through the Pizza Orders API. """ def __init__(self, config: PizzaOrderingToolConfig = PizzaOrderingToolConfig()): """ Initializes the PizzaOrderingTool with the provided configuration. """ super().__init__(config) self.api_endpoint = config.api_endpoint self.supported_pizzas = config.supported_pizzas self.api_key = config.api_key self.tool_name = config.title or self.input_schema.__name__ self.tool_description = config.description or self.__doc__ def run(self, params: PizzaOrderInputSchema) -> dict: """ Executes the tool's main logic to place an order and process payment. """ # Validate pizza type if params.pizza_type not in self.supported_pizzas: raise ValueError(f"Pizza type '{params.pizza_type}' is not supported.") # Simulate placing the order order_id = self.place_order(params) estimated_time = self.get_estimated_delivery_time(order_id) amount = self.calculate_payment(params) payment_status = self.process_payment(order_id, amount) # Prepare outputs confirmation = OrderConfirmationSchema( order_id=order_id, estimated_delivery_time=estimated_time, status=OrderStatus.CONFIRMED ) payment = PaymentDetailsSchema( amount=amount, payment_status=payment_status ) return { "confirmation": confirmation, "payment": payment } def place_order(self, params: PizzaOrderInputSchema) -> str: """Simulates placing an order and returns an order ID.""" return "ORD123456" def get_estimated_delivery_time(self, order_id: str) -> str: """Simulates retrieving the estimated delivery time.""" return "30 minutes" def calculate_payment(self, params: PizzaOrderInputSchema) -> float: base_prices = { "Margherita": 8.99, "Pepperoni": 9.99, "Veggie": 10.99, "Hawaiian": 9.49 } size_multipliers = { PizzaSize.SMALL: 1.0, PizzaSize.MEDIUM: 1.2, PizzaSize.LARGE: 1.5 } topping_price = 0.99 # Price per additional topping base_price = base_prices[params.pizza_type] size_multiplier = size_multipliers[params.size] toppings_cost = sum( topping_price + (0.5 if topping.extra_cheese else 0) for topping in params.toppings ) if params.toppings else 0 total = (base_price * size_multiplier + toppings_cost) * params.quantity return total def process_payment(self, order_id: str, amount: float) -> str: """Simulates payment processing.""" return "Paid"

⑥ Example Usage：最后用if __name__ == "__main__"演示实例化与调用，既方便测试，也充当用户文档：

################# # Example Usage # ################# if __name__ == "__main__": from rich.console import Console console = Console() pizza_tool = PizzaOrderingTool() order_input = PizzaOrderInputSchema( customer_name="Jane Smith", pizza_type="Veggie", size=PizzaSize.MEDIUM, crust=CrustType.THIN, toppings=[ Topping(name="Olives", extra_cheese=False), Topping(name="Mushrooms", extra_cheese=True) ], quantity=2 ) try: outputs = pizza_tool.run(order_input) console.print(outputs) except Exception as e: console.print(f"[red]Error:[/red] {e}")

最佳实践：Do's 与 Don'ts

指南最后给出了一份精炼的工程规范清单，值得在写每个工具时对照检查：

应当做的（Do's）

• 导入语句统一放在脚本顶部，且不带 section 注释块；
• 严格遵守标准结构与段落顺序，保证一致性；
• 使用清晰、有描述性的命名；
• 用 docstring 和注释充分文档化代码（docstring 还会作为 schema 描述注入给 LLM）；
• 充分利用 Pydantic 做输入校验；
• 提供信息丰富的错误消息，妥善处理异常；
• 保持函数小而专注，复杂逻辑拆成辅助方法；
• 提交uv.lock保证依赖一致；
• 手动创建干净的requirements.txt，与pyproject.toml非开发依赖对齐。

不要做的（Don'ts）

• 不要硬编码值——使用配置参数或环境变量；
• 避免全局变量——状态保持在工具作用域内；
• 不要过度复杂化——坚守单一职责，不加无关功能；
• 不要忽视安全——API key 等敏感信息必须走环境变量；
• 不要忽视性能——处理大数据集或外部 API 调用时要优化；
• 不要跳过输入校验——永远不要假设输入合法；
• 不要自动生成requirements.txt——可能带入无用甚至开发依赖，手动只写运行时依赖。

融入 Agent 工作流：从工具到系统的最后一公里

工具就绪后，集成进 Agent 的方式非常直接。参考主 README 中的链式模式，你可以创建 Query Agent 让其输出与搜索工具输入 schema 对齐的查询列表，然后把 Agent 输出直接喂给SearXNGTool之类的工具：

# 查询 Agent 的 output_schema 与工具的 input_schema 对齐后即可直接串联 query_agent = AtomicAgentQueryAgentInputSchema, SearXNGSearchTool.input_schema), model="gpt-5-mini", system_prompt_generator=SystemPromptGenerator(...), ) )

这样设计的好处是可替换性：今天用 SearXNG，明天换成 Tavily，只需更换工具实例或调整输出 schema 对齐即可，Agent 主体无需改动。

小结

Atomic Forge 以"可下载工具文件夹"而非软件包的形式，把轻量接入、完全掌控、按需依赖的开发体验带给了 Atomic Agents 生态。你可以通过atomicCLI 或手动复制，在数秒内获得 14 个开箱即用的原子能力；也可以参照 tool_structure.md 的六段式规范，结合BaseIOSchema/BaseToolConfig/BaseTool三大基类，写出自己的第一个 Atomic Tool。无论哪条路线，最终交付的都是一致的协议——清晰的输入输出 schema、一个run()入口、自包含的目录结构和配套测试，这正是"原子化"构建 AI 应用的核心体验。

• AI Agent
• Agent 框架
• MCP 服务
• 后端