AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载本篇文章以 Atomic Agents 仓库中的核心模块索引.claude/.codebase-info/modules.md为骨架系统拆解这套原子化构建 AI Agent框架的模块划分与内部依赖关系从承载 Agent 运行生命周期的AtomicAgent到定义类型化契约的base层、负责系统提示词与对话记忆的context层、接入 Model Context Protocol 的connectors/mcp层再到atomic-assembler、atomic-forge、atomic-examples三个配套子项目。读完本文你将掌握每个模块的职责边界、关键公开 API以及它们如何通过BaseChatHistory、BaseIOSchema等接缝组合成可扩展的 Agent 系统。模块总览核心框架与三个子项目Atomic Agents 仓库采用核心框架 生态子项目的整体布局与模块索引的划分一致目录定位内容atomic-agents/atomic_agents/核心框架Agent 运行时、类型化基类、上下文与记忆、MCP 连接器、工具类atomic-assembler/命令行工具基于 Textual TUI 浏览并安装 Forge 工具到用户项目atomic-forge/工具库13 个遵循BaseTool模式的独立小工具atomic-examples/示例应用16 个可运行的参考应用核心框架内部又细分为agents、base、context、connectors/mcp、utils五个模块下文逐一展开。agents 模块Agent 运行生命周期的中枢位置atomic-agents/atomic_agents/agents/atomic_agent.pyagents模块是整个框架的运行时中枢公开AtomicAgent、AgentConfig、BasicChatInputSchema、BasicChatOutputSchema四个核心对象。其中AtomicAgent[InputSchema, OutputSchema]采用 PEP 695 泛型语法输入/输出模式必须继承自BaseIOSchema。AgentConfigAgent 的完整配置面从配置定义可以看到AgentConfig是一个 Pydantic 模型其字段含义如下client必填Instructor 客户端负责与语言模型交互通过instructor.from_openai(OpenAI())等方式创建model默认gpt-5-mini指定用于生成响应的模型history可选类型为BaseChatHistory默认构造时会回退到框架内置的ChatHistorysystem_prompt_generator可选默认使用SystemPromptGenerator也可传入任意BaseSystemPromptGenerator子类system_role默认system设为None则不发送系统提示词assistant_role默认assistantGemini 系列需改为modeltool_result_role默认None用于工具结果与上下文中途注入未显式设置时自动探测——assistant_role为modelGemini时取user否则取systemmodeInstructor 的结构化输出模式Mode.TOOLS、Mode.JSON等默认Mode.TOOLSmodel_api_parameters透传给 API 提供商的额外参数如temperature、max_tokensmax_context_tokens全上下文系统提示词 历史 工具的 token 上限超出时自动裁剪最旧对话轮次。四种运行入口AtomicAgent提供四种调用方式覆盖同步/异步与流式/非流式run(user_input)同步调用返回OutputSchema实例run_stream(user_input)同步生成器逐个产出部分响应最后返回完整响应run_async(user_input)异步调用要求client是AsyncInstructorrun_async_stream(user_input)异步生成器流式产出部分响应。从run的实现可以看出典型调用链为_trim_context()裁剪超限历史 →history.initialize_turn()开启新轮次 → 写入用户消息 →_prepare_messages()组装 system history 消息 → 通过client.chat.completions.create(..., response_modelself.output_schema)请求结构化输出 → 把响应按assistant_role写回历史。run_stream与run_async_stream则改用create_partial利用流式补全逐步产出OutputSchema的部分实例。泛型参数的三级回退机制input_schema/output_schema属性通过三级回退确定实际模式类源码见此处类属性_input_schema_cls/_output_schema_cls由__init_subclass__在子类创建时捕获泛型参数覆盖继承式用法MyAgent(AtomicAgent[Schema1, Schema2])实例属性__orig_class__覆盖动态实例化用法AtomicAgent[Schema1, Schema2]()默认回退到BasicChatInputSchema/BasicChatOutputSchema。BasicChatInputSchema与BasicChatOutputSchema分别是含chat_message: str字段的输入/输出模式定义于同一文件顶部。base 模块定义一切组件遵守的类型化契约位置atomic-agents/atomic_agents/base/base模块是一切实现必须遵守的约定层包含五个关键文件其中BaseIOSchema、BaseTool、BaseToolConfig、VideoURL通过包根导出。BaseIOSchema强制文档化的 Pydantic 基类BaseIOSchema是BaseModel的直接子类其核心约束是每个模式类必须有非空的 docstring且该 docstring 会被用作模式的 description。实现位于__pydantic_init_subclass__钩子中源码第 16-30 行若 docstring 缺失且非 Instructor 生成的模式会抛出ValueError。同时model_json_schema()被覆写把干净的 docstring 注入 JSON Schema 的description把类名注入title。此外它还实现了__str__与__rich__便于终端展示。BaseTool / BaseResource / BasePrompt三套同构的组件契约BaseTool[In, Out]、BaseResource[In, Out]、BasePrompt[In, Out]三者的结构完全同构均继承ABC并带两个泛型模式参数各自携带*Config配置模型BaseToolConfig、BaseResourceConfig、BasePromptConfig字段一致title与description均可选用于覆盖默认名称/描述名称与描述属性tool_name/tool_description、resource_name/resource_description、prompt_name/prompt_description默认取自输入模式的 JSON Schema 的title/description各自声明一个抽象执行方法BaseTool.run(params) - OutputSchema、BaseResource.read(params) - OutputSchema、BasePrompt.generate(params) - OutputSchema与AtomicAgent相同都通过__init_subclass__捕获泛型参数并提供三级回退的input_schema/output_schema属性。multimodal.py补齐视频输入的VideoURLVideoURL是 Instructor 未提供的视频内容类型补充Instructor 原生仅有 Image、Audio、PDF。它包含url必填HTTP(S) 或 data: URL、fps帧采样率可选、detail细节级别可选三个字段并通过to_openai()输出为 OpenAI 兼容的{type: video_url, video_url: {...}}content part支持 MiniMax、Qwen-VL 等接受video_url的提供商。context 模块系统提示词组装与对话记忆位置atomic-agents/atomic_agents/context/context模块解决两个问题如何动态组装系统提示词以及如何保存多轮对话记忆。SystemPromptGenerator四段式系统提示词BaseDynamicContextProvider是最小上下文注入接口只需提供title与get_info() - strBaseSystemPromptGenerator声明generate_prompt()抽象方法并持有context_providers字典。内置的SystemPromptGenerator支持三个构造参数backgroundAgent 背景描述默认[This is a conversation with a helpful and friendly AI assistant.]steps内部执行步骤列表output_instructions输出指令列表构造时会自动追加两条始终使用 JSON schema 响应、始终利用可用上下文增强回答。generate_prompt()按IDENTITY and PURPOSE→INTERNAL ASSISTANT STEPS→OUTPUT INSTRUCTIONS→EXTRA INFORMATION AND CONTEXT遍历每个 provider输出## {title}get_info()内容的顺序拼装 Markdown 文本。注册/注销 context provider 可通过AtomicAgent.register_context_provider/unregister_context_provider/get_context_provider完成。BaseChatHistory记忆的可插拔接缝BaseChatHistory是一个纯接口型 ABC不定义任何状态与行为只声明AtomicAgent依赖的方法契约——initialize_turn、add_message、get_history、get_current_turn_id、delete_turn_id、get_message_count、dump、load、copy以及两个必须维护的实例属性history与current_turn_id。由于AgentConfig.history的类型就是BaseChatHistory任何符合该契约的后端持久化存储、数据库、按 session 隔离的记忆都能直接替换内置实现。需要注意若自定义后端携带额外状态如数据库句柄、session_id必须覆写copy()返回自身类型否则AtomicAgent.reset_history()会把后端静默替换为普通内存历史后续写入将不再到达存储。ChatHistory内置的内存实现ChatHistory是框架内置实现关键能力包括turn 分组每次调用initialize_turn()生成 UUID 作为turn_id同一轮次的用户消息与助手回复共享该 IDdelete_turn_id(turn_id)可整轮删除_trim_context()依赖此机制按轮裁剪多模态支持内容支持 Instructor 的Image/Audio/PDF及框架的VideoURL统一定义为MULTIMODAL_TYPESget_history()会递归提取任意嵌套深度的多模态对象并生成 Pydanticexclude规格序列化为混合 content 数组VideoURL会经to_openai()转成 dict溢出管理max_messages参数约束最大消息数超限时移除最早消息序列化dump()输出含消息类名module.ClassName、数据与 turn_id 的 JSON 字符串load()反序列化时通过__import__还原模式类并把Image/PDF的字符串路径重新转回Path。connectors/mcp 模块接入 Model Context Protocol位置atomic-agents/atomic_agents/connectors/mcp/该模块把 MCP 服务器的工具、资源、提示词暴露为 Atomic Agents 组件通过包根导出提供以下公开 APIMCPFactory工厂类用于创建基于 MCP 的组件实例MCPDefinitionService定义服务配合MCPTransportType传输类型、MCPToolDefinition、MCPResourceDefinition、MCPPromptDefinition描述远端定义SchemaTransformer模式转换器负责把 MCP 模式映射为 Atomic Agents 的BaseIOSchemafetch_mcp_tools/fetch_mcp_resources/fetch_mcp_prompts同步获取函数fetch_mcp_tools_async/fetch_mcp_resources_async/fetch_mcp_prompts_async异步版本create_mcp_orchestrator_schema、fetch_mcp_attributes_with_schema编排与带模式拉取的辅助 API。实际接入示例可参考仓库中的 mcp-agent 示例其example-client提供 stdio、HTTP、SSE 等多种客户端接入方式example-mcp-server展示了如何实现 MCP 工具、资源与提示词服务端。utils 模块token 计数与消息格式化位置atomic-agents/atomic_agents/utils/token_counter.py基于 LiteLLM 的 provider 无关 token 计数。TokenCounter提供count_messages、count_text、get_max_tokens、count_context四个方法count_context返回TokenCountResultNamedTuple字段为total/system_prompt/history/tools/model/max_tokens/utilization且满足加法恒等式system_prompt history tools total。get_token_counter()返回模块级单例format_tool_message.py工具消息格式化工具。AtomicAgent的上下文管理正是建立在utils之上get_context_token_count()会按当前mode精确序列化上下文——TOOLS 模式使用generate_openai_schema生成实际 tools 参数JSON 模式则把 schema 追加到系统消息随后_trim_context()在超出max_context_tokens时逐轮删除最旧 turn直到上下文回到上限内若单轮自身就超限会抛出ValueError提示增大上限或精简系统提示词。生态子项目组装器、工具库与示例atomic-assemblerTextual 终端安装器位置atomic-assembler/atomic_assembler/基于 Textual 构建的 TUI用于浏览并安装 Forge 工具到用户项目。关键文件包括main.pymain()入口支持--enable-logging、--version两个 argparse 参数、app.pyAtomicAssembler(App)主应用、screens/下的四个界面main_menu、atomic_tool_explorer、file_explorer、tool_info_screen、widgets/组件集合、utils.pyGithubRepoCloner与AtomicToolManager负责克隆与工具管理以及constants.pyGitHub URL 与TOOLS_SUBFOLDER常量。atomic-forge13 个独立工具位置atomic-forge/tools/13 个独立小工具每个都是遵循BaseTool模式的迷你工程包括calculator、weather、webpage_scraper、searxng_search、tavily_search、wikipedia_search、youtube_transcript_scraper、pdf_reader、arxiv_search、hackernews_search、bocha_search、datetime_tool、fia_signals。每个工具目录包含tool/实现、tests/测试、pyproject.toml、requirements.txt与README.mdassembler 复制到用户项目时会跳过构建文件pyproject.toml、requirements.txt、uv.lock。工具的作者指南见 atomic-forge/guides/tool_structure.md。atomic-examples16 个可运行参考应用位置atomic-examples/覆盖多轮对话、流式输出、自定义模式、多提供商、多模态、RAG、MCP、DSPy 集成、FastAPI 服务、深度研究编排等场景的参考应用例如basic-multimodal营养标签图像分析、basic-pdf-analysis、rag-chatbot、mcp-agent、web-search-agent、youtube-summarizer、persistent-memory、progressive-disclosure等可作为上手与二次开发的起点。组装视角Agent 如何把各模块串起来从整体看一个最小 Agent 的组装链路是用继承BaseIOSchema的模式类定义输入输出 → 用AgentConfig装配 Instructor 客户端、SystemPromptGenerator与ChatHistory→ 交给AtomicAgent[In, Out]运行 → 用run/run_stream/run_async/run_async_stream与模型交互 → 通过 hook 系统register_hook/unregister_hook/clear_hooks支持parse:error、completion:kwargs、completion:response、completion:error、completion:last_attempt以及token:counted事件监控运行 → 超出上下文上限时由_trim_context()按轮裁剪。AtomicAgent的全部依赖集中在base/类型契约、context/提示词与记忆、utils/token 计数以及 Instructor模块间仅通过抽象基类耦合这正是替换任一组件如换成持久化BaseChatHistory后端、自定义BaseSystemPromptGenerator而不改动核心逻辑的原因。赞分享AI AgentAgent 框架MCP 服务后端【免费下载链接】atomic-agentsBuilding AI agents, atomically项目地址https://gitcode.com/gh_mirrors/at/atomic-agents点击查看免费下载相关推荐Atomic Agents 框架完全指南基于原子化组件构建模块化 AI AgentAtomic Agents 框架完全指南基于原子化组件构建模块化 AI Agent Atomic Agents 是当前仓库 gh_mirrors/at/atAI AgentAgent 框架MCP 服务后端sysinfo 多平台适配实战Windows、Linux、macOS 系统信息获取完整教程sysinfo 多平台适配实战Windows、Linux、macOS 系统信息获取完整教程 sysinfo 是一个强大的跨平台系统信息获取库能够帮助开发者轻大模型本地部署AI 应用Atomic Agents 框架入门指南用原子化思想构建可靠、可组合的 AI Agent 应用Atomic Agents 框架入门指南用原子化思想构建可靠、可组合的 AI Agent 应用 本文基于开源仓库 atomic agents 的 READAI AgentAgent 框架MCP 服务后端上一篇Playnite游戏管理器跨平台整合你的全部游戏收藏下一篇Obsidian附件管理终极解决方案自定义路径插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考