
AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载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而是一个可下载工具的文件夹。初看有些反直觉但官方列出了三点理由恰好也是这套方案的价值所在完全掌控Full Control下载到本地后每个工具的所有权完全属于你。喜欢某个搜索工具但希望按自己的方式排序结果直接改不会影响其他使用者当然如果你的改进对别人也有价值也欢迎向 Atomic Forge 仓库提交 Pull Request。依赖管理Dependency Management工具一旦下载就位于你自己的代码库中依赖的引入、升级、冲突排查都由你自主掌控。轻量Lightweight每个工具都是独立组件你可以只下载真正需要的工具而不是让项目被一堆无关依赖撑大——正如官方举例所说如果你不用 Calculator 工具就没必要让项目背上 Sympy 这个依赖。这种复制进你的代码库的交付方式与传统的库依赖模式形成鲜明对比不是引入一个巨大的 SDK而是把恰好你需要的那一个能力搬进项目并保留完全改造的自由度。工具清单14 个开箱即用的原子能力Atomic Forge 目前收录了 14 个工具全部位于 atomic-forge/tools 目录下每个工具目录内都包含独立的tool/源码目录、tests/测试目录、README.md和pyproject.toml工具功能定位使用说明arXiv Search通过免费的 arXiv 公共 API 搜索学术论文无需 API keyBoCha SearchBoCha 搜索服务接入需要 BoCha API keyCalculator基于 SymPy 的数学表达式求值支持算术、幂、三角函数等DateTime时区感知的 now / parse / convert / shift / diff处理跨时区时间计算Fía SignalsFía 信号数据接入面向金融信号场景Hacker News Search通过免费的 Algolia API 搜索 HN 故事、评论、Show HN、Ask HN无需 API keyPDF Reader从本地或远程 PDF 提取文本与元数据支持页范围过滤文档解析场景SearXNG Search接入 SearXNG 元搜索引擎聚合多源结果并保护隐私需自建/指定 SearXNG 实例Serply SearchSerply 搜索 API 接入需 Serply API keyTavily Search接入专为 AI Agent 设计的 Tavily 搜索 API需 Tavily API keyWebpage Scraper网页内容抓取网页正文提取场景Weather通过免费的 Open-Meteo API 获取当前天气与逐日/逐时预报无需 API key支持城市名或经纬度Wikipedia Search搜索任意语言版本的 Wikipedia返回标题、URL、摘要及可选的全文提取无需 API keyYouTube Transcript Scraper提取 YouTube 视频字幕/转录文本配合总结类 Agent 使用从列表中可以看出几个共性多数工具调用免费公共 APIarXiv、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继承BaseIOSchemafrom 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(..., descriptionMathematical expression to evaluate. For example, 2 2.) ################# # OUTPUT SCHEMA # ################# class CalculatorToolOutputSchema(BaseIOSchema): Schema for the output of the CalculatorTool. result: str Field(..., descriptionResult 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(resultstr(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(expressionsin(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(expression2 2) result calculator_tool.run(input_schema) assert result CalculatorToolOutputSchema(result4.00000000000000)这个测试同时验证了两件事计算结果正确以及返回对象是严格的CalculatorToolOutputSchema实例而非普通 dict这正是框架强调结构化输出的体现。用多工具组合理解可插拔设计单独看 Calculator 可能觉得简单但把它放进 Agent 工作流里可插拔的价值就显现了。以 deep-research 示例为例其中的 Decider Agent 会判断用户问题把任务路由给使用不同工具的搜索型 Agent——而 web-search-agent 中的SearXNGSearchTool则展示了另一种复杂度更高的真实工具形态。以 Tavily Search 为例它的配置更丰富完整源码在 tool/tavily_search.pyclass 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.tomlPython 项目元数据与依赖声明由 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, pydantic2.8.2,3.0.0, requests2.28.0,3.0.0, ] [dependency-groups] dev [ coverage7.0.0,8.0.0, pytest8.0.0,9.0.0, pytest-cov5.0.0,6.0.0, python-dotenv1.0.0,2.0.0, rich13.7.0,14.0.0, ] [tool.uv.sources] atomic-agents { workspace true }对应的requirements.txt只保留运行时依赖atomic-agents1.0.0,2.0.0 pydantic2.8.2,3.0.0 requests2.28.0,3.0.0三点纪律需要记住requirements.txt只含[project.dependencies]中的包绝不能包含[dependency-groups.dev]下的开发依赖手写而非自动生成。真实工具与指南完全一致例如 calculator 的 pyproject.toml 声明requires-python 3.12与sympy1.12,2.0.0等运行时依赖。继承规则三类基类缺一不可为保证框架内的一致性你的工具类必须严格继承对应基类组件必须继承输入/输出 SchemaBaseIOSchema配置类BaseToolConfig主工具类BaseTool遵守这套继承规则工具才能与框架其他组件无缝集成。需要特别说明的是BaseToolConfig的title/description覆盖能力base_tool.py默认情况下工具名取自输入 schema 的 title、工具描述取自 schema docstring但某些边界场景需要手动覆盖——例如一个工具做网页搜索、另一个在内部文档向量库中检索你可能希望让 LLM 在回答公司内部问题时优先调用向量检索工具而不是网页搜索工具此时通过配置覆盖描述就是最直接的手段。六段式标准结构指南明确规定一个 Atomic Tool 的源码应严格按以下顺序组织每个 section除 imports 外用包含 section 名的注释块明确分隔Imports导入Input Schema输入 SchemaOutput Schema(s)输出 Schema可有多个Configuration配置Main Tool Logic主工具与逻辑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(..., descriptionName of the topping.) extra_cheese: bool Field(False, descriptionAdd extra cheese to this topping.) class PizzaOrderInputSchema(BaseIOSchema): Captures customer details and order specifics for placing a pizza order. customer_name: str Field(..., descriptionName of the customer placing the order.) pizza_type: str Field(..., descriptionType of pizza to order (e.g., Margherita, Pepperoni).) size: PizzaSize Field(..., descriptionSize of the pizza.) crust: CrustType Field(..., descriptionType of crust for the pizza.) toppings: Optional[List[Topping]] Field(None, descriptionList of additional toppings.) quantity: int Field(..., descriptionNumber 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(..., descriptionUnique identifier for the order.) estimated_delivery_time: str Field(..., descriptionEstimated time for order delivery.) status: OrderStatus Field(..., descriptionCurrent status of the order.) class PaymentDetailsSchema(BaseIOSchema): Payment information for the order. amount: float Field(..., descriptionTotal amount to be paid.) currency: str Field(USD, descriptionCurrency of the payment.) payment_status: str Field(..., descriptionStatus of the payment (e.g., Paid, Pending).)订单确认与支付信息拆成两个独立 schema同样都继承BaseIOSchema。④ Configuration通过配置类开放自定义行为敏感信息如 API key从环境变量读取################# # Configuration # ################# class PizzaOrderingToolConfig(BaseToolConfig): Configuration for the PizzaOrderingTool. api_endpoint: str Field( defaulthttps://api.pizzaorders.com/v1/orders, descriptionAPI endpoint for processing pizza orders. ) supported_pizzas: List[str] Field( default[Margherita, Pepperoni, Veggie, Hawaiian], descriptionList of supported pizza types. ) api_key: str Field( defaultos.getenv(PIZZA_API_KEY), descriptionAPI key for authenticating with the pizza ordering service. ) title: Optional[str] Field( defaultPizza Ordering Tool, descriptionOverride the default title of the tool. ) description: Optional[str] Field( defaultA tool to place pizza orders and process payments., descriptionOverride 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 tools main logic to place an order and process payment. # Validate pizza type if params.pizza_type not in self.supported_pizzas: raise ValueError(fPizza 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_idorder_id, estimated_delivery_timeestimated_time, statusOrderStatus.CONFIRMED ) payment PaymentDetailsSchema( amountamount, payment_statuspayment_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_nameJane Smith, pizza_typeVeggie, sizePizzaSize.MEDIUM, crustCrustType.THIN, toppings[ Topping(nameOlives, extra_cheeseFalse), Topping(nameMushrooms, extra_cheeseTrue) ], quantity2 ) try: outputs pizza_tool.run(order_input) console.print(outputs) except Exception as e: console.print(f[red]Error:[/red] {e})最佳实践Dos 与 Donts指南最后给出了一份精炼的工程规范清单值得在写每个工具时对照检查应当做的Dos导入语句统一放在脚本顶部且不带 section 注释块严格遵守标准结构与段落顺序保证一致性使用清晰、有描述性的命名用 docstring 和注释充分文档化代码docstring 还会作为 schema 描述注入给 LLM充分利用 Pydantic 做输入校验提供信息丰富的错误消息妥善处理异常保持函数小而专注复杂逻辑拆成辅助方法提交uv.lock保证依赖一致手动创建干净的requirements.txt与pyproject.toml非开发依赖对齐。不要做的Donts不要硬编码值——使用配置参数或环境变量避免全局变量——状态保持在工具作用域内不要过度复杂化——坚守单一职责不加无关功能不要忽视安全——API key 等敏感信息必须走环境变量不要忽视性能——处理大数据集或外部 API 调用时要优化不要跳过输入校验——永远不要假设输入合法不要自动生成requirements.txt——可能带入无用甚至开发依赖手动只写运行时依赖。融入 Agent 工作流从工具到系统的最后一公里工具就绪后集成进 Agent 的方式非常直接。参考主 README 中的链式模式你可以创建 Query Agent 让其输出与搜索工具输入 schema 对齐的查询列表然后把 Agent 输出直接喂给SearXNGTool之类的工具# 查询 Agent 的 output_schema 与工具的 input_schema 对齐后即可直接串联 query_agent AtomicAgentQueryAgentInputSchema, SearXNGSearchTool.input_schema), modelgpt-5-mini, system_prompt_generatorSystemPromptGenerator(...), ) )这样设计的好处是可替换性今天用 SearXNG明天换成 Tavily只需更换工具实例或调整输出 schema 对齐即可Agent 主体无需改动。小结Atomic Forge 以可下载工具文件夹而非软件包的形式把轻量接入、完全掌控、按需依赖的开发体验带给了 Atomic Agents 生态。你可以通过atomicCLI 或手动复制在数秒内获得 14 个开箱即用的原子能力也可以参照 tool_structure.md 的六段式规范结合BaseIOSchema/BaseToolConfig/BaseTool三大基类写出自己的第一个 Atomic Tool。无论哪条路线最终交付的都是一致的协议——清晰的输入输出 schema、一个run()入口、自包含的目录结构和配套测试这正是原子化构建 AI 应用的核心体验。赞分享AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载相关推荐IceCubesApp 深度解析如何从零构建一个支持 4 个 Apple 平台的纯 SwiftUI Mastodon 客户端IceCubesApp 深度解析如何从零构建一个支持 4 个 Apple 平台的纯 SwiftUI Mastodon 客户端 IceCubesApp 是一个完移动开发社交wvp-GB28181-pro 容器化部署教程3 步快速搭建支持直播与云台控制的 GB28181 国标视频平台wvp GB28181 pro 容器化部署教程3 步快速搭建支持直播与云台控制的 GB28181 国标视频平台 手头有一台云主机和一批海康、大华的国标摄像头后端音视频前端Atomic Forge 工具箱使用指南13 个即插即用 AI 工具与 Assembler CLI 下载实战Atomic Forge 工具箱使用指南13 个即插即用 AI 工具与 Assembler CLI 下载实战 Atomic Forge 是 Atomic AgAI AgentAgent 框架MCP 服务后端上一篇高效磁盘清理利器Czkawka与Krokiet完整指南下一篇gRPC实战案例从Hello World到生产级应用创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考