Atomic Agents

什么是 Atomic Agents？

Atomic Agents 框架基于原子性设计理念，旨在提供一个极度轻量且模块化的框架，用于构建智能体 AI 流水线和应用程序，同时不牺牲开发者体验和可维护性。

可以将其想象成用乐高积木构建 AI 应用程序——每个组件（智能体、工具、上下文提供者）都具有以下特性：
- 单一职责：专注于做好一件事
- 可复用：可在多个流水线中使用
- 可组合：易于与其他组件结合
- 可预测：生成一致、可靠的输出

该框架构建在 Instructor 和 Pydantic 之上，使您能够使用您熟悉和喜爱的软件工程原则来创建 AI 应用程序。

新消息：加入我们的 Discord 社区 discord.gg/J3W9b5AZJR 和官方子论坛 /r/AtomicAgents！

目录

• Atomic Agents
• 什么是 Atomic Agents？
• 目录
• 快速开始
  • 安装
  • 快速示例
• 为什么选择 Atomic Agents？
• 核心概念
  • 智能体的构成
  • 上下文提供者
  • 链式智能体与工具
• 示例与文档
  • 快速入门示例
  • 完整示例
• 🚀 版本 2.0 发布！
  • v2.0 的关键变更：
  • ⚠️ 从 v1.x 升级
• Atomic Forge 与 CLI
  • 运行 CLI
• 项目结构
• 提供商与模型兼容性
• 贡献
• 许可证
• 其他资源
• 星标历史

快速开始

安装

使用 pip 安装 Atomic Agents：

pip install atomic-agents

确保同时安装您要使用的提供商。提供商 SDK 可作为 instructor 的可选依赖安装：

pip install instructor[groq]        # 用于 Groq
pip install instructor[anthropic]   # 用于 Anthropic
pip install instructor[google-genai] # 用于 Gemini

OpenAI 默认包含在内。有关所有受支持提供商的完整列表，请参阅 Instructor 文档。

安装完成后，还会安装 CLI 工具 Atomic Assembler，可用于下载工具（未来还将支持智能体和流水线）。

快速示例

以下是一个快速代码片段，展示了使用 Atomic Agents 创建功能强大的智能体是多么简单：

from pydantic import Field
from openai import OpenAI
import instructor
from atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BaseIOSchema
from atomic_agents.context import SystemPromptGenerator, ChatHistory

# 定义自定义输出模式
class CustomOutputSchema(BaseIOSchema):
    """
    自定义输出模式的文档字符串
    """
    chat_message: str = Field(..., description="智能体的聊天消息。")
    suggested_questions: list[str] = Field(..., description="建议的后续问题。")

# 设置系统提示
system_prompt_generator = SystemPromptGenerator(
    background=["该助手知识渊博、乐于助人，并能建议后续问题。"],
    steps=[
        "分析用户的输入以理解上下文和意图。",
        "制定相关且信息丰富的回复。",
        "为用户生成 3 个建议的后续问题。"
    ],
    output_instructions=[
        "提供清晰简洁的信息以响应用户查询。",
        "每个回复结尾包含 3 个相关建议问题供用户参考。"
    ]
)

# 初始化 OpenAI 客户端
client = instructor.from_openai(OpenAI())

# 初始化智能体
agent = AtomicAgent[BasicChatInputSchema, CustomOutputSchema](
    config=AgentConfig(
        client=client,
        model="gpt-5-mini",
        system_prompt_generator=system_prompt_generator,
        history=ChatHistory(),
    )
)

# 使用示例
if __name__ == "__main__":
    user_input = "告诉我关于 atomic agents 框架的信息"
    response = agent.run(BasicChatInputSchema(chat_message=user_input))
    print(f"智能体: {response.chat_message}")
    print("建议的问题：")
    for question in response.suggested_questions:
        print(f"- {question}")

为什么选择 Atomic Agents？

虽然现有的智能体 AI 框架侧重于构建自主的多智能体系统，但它们往往缺乏实际应用所需的控制和可预测性。企业需要能够产生一致、可靠输出并与品牌和目标保持一致的 AI 系统。

Atomic Agents 通过提供以下特性满足这一需求：

• 模块化：通过组合小型、可复用的组件构建 AI 应用程序。
• 可预测性：定义清晰的输入和输出模式以确保行为一致。
• 可扩展性：轻松替换组件或集成新组件，而不会影响整个系统。
• 可控性：从系统提示到工具集成，独立微调系统的每个部分。

所有逻辑和控制流均使用 Python 编写，使开发者能够应用传统的软件开发中的最佳实践和工作流程，而不会牺牲灵活性和清晰度。

核心概念

智能体的构成

在 Atomic Agents 中，智能体由以下几个关键组件组成：

• 系统提示：定义智能体的行为和目的。
• 输入模式：指定智能体输入的结构和验证规则。
• 输出模式：指定智能体输出的结构和验证规则。
• 历史记录：存储对话历史或其他相关数据。
• 上下文提供者：在运行时将动态上下文注入到智能体的系统提示中。

以下是高层架构示意图：

上下文提供者

Atomic Agents 允许您使用上下文提供者来增强智能体的动态上下文。上下文提供者使您能够在运行时向智能体的系统提示注入额外信息，从而使智能体更加灵活并感知上下文。

要使用上下文提供者，请创建一个继承自 BaseDynamicContextProvider 的类，并实现 get_info() 方法，该方法返回要添加到系统提示的上下文字符串。

以下是一个简单的示例：

from atomic_agents.context import BaseDynamicContextProvider

class SearchResultsProvider(BaseDynamicContextProvider):
    def __init__(self, title: str, search_results: List[str]):
        super().__init__(title=title)
        self.search_results = search_results

    def get_info(self) -> str:
        return "\n".join(self.search_results)

然后，您可以将上下文提供者注册到智能体：

# 使用动态数据初始化上下文提供者
search_results_provider = SearchResultsProvider(
    title="搜索结果",
    search_results=["结果 1", "结果 2", "结果 3"]
)

# 将上下文提供者注册到智能体
agent.register_context_provider("search_results", search_results_provider)

这样，您的智能体就可以在其系统提示中包含搜索结果（或任何其他上下文），从而根据最新信息增强其响应。

链式智能体与工具

Atomic Agents 通过对齐输入和输出模式，使智能体和工具的链式调用变得简单。这种设计允许您轻松替换组件，从而提高 AI 应用程序的模块化和可复用性。

假设您有一个生成搜索查询的智能体，并且您希望将这些查询与不同的搜索工具一起使用。通过将智能体的输出模式与搜索工具的输入模式对齐，您可以轻松地将它们链式调用或在不同的搜索提供商之间切换。

以下是如何实现这一目标：

import instructor
import openai
from pydantic import Field
from atomic_agents import BaseIOSchema, AtomicAgent, AgentConfig
from atomic_agents.context import SystemPromptGenerator

# 导入要使用的搜索工具
from web_search_agent.tools.searxng_search import SearXNGSearchTool

# 定义查询智能体的输入模式
class QueryAgentInputSchema(BaseIOSchema):
    """QueryAgent 的输入模式。"""
    instruction: str = Field(..., description="用于生成搜索查询的指令。")
    num_queries: int = Field(..., description="要生成的查询数量。")

# 初始化查询智能体
query_agent = AtomicAgent[QueryAgentInputSchema, SearXNGSearchTool.input_schema](
    config=AgentConfig(
        client=instructor.from_openai(openai.OpenAI()),
        model="gpt-5-mini",
        system_prompt_generator=SystemPromptGenerator(
            background=[
                "您是一位智能查询生成专家。",
                "您的任务是基于给定的指令生成指定数量的多样化且高度相关的查询。"
            ],
            steps=[
                "接收指令和要生成的查询数量。",
                "以 JSON 格式生成查询。"
            ],
            output_instructions=[
                "确保每个查询都是唯一且相关的。",
                "以预期的模式提供查询。"
            ],
        ),
    )
)

在此示例中：

• 模块化：通过将 query_agent 的 output_schema 设置为与 SearXNGSearchTool 的 input_schema 匹配，您可以直接将智能体的输出用作工具的输入。
• 可替换性：如果您决定切换到不同的搜索提供商，只需导入不同的搜索工具并相应地更新 output_schema。

例如，要切换到另一个搜索服务：

# 导入不同的搜索工具
from web_search_agent.tools.another_search import AnotherSearchTool

# 更新输出模式
query_agent.config.output_schema = AnotherSearchTool.input_schema

这种设计模式简化了智能体和工具的链式调用过程，使您的 AI 应用程序更易于适应和维护。

示例与文档

访问文档站点 »

快速入门示例

完整示例列表请参见 examples 目录。我们努力为每个示例提供详尽的文档，但如果某些内容不清楚，请随时提 issue 或 pull request 以改进文档。

有关完整可运行的示例，请参阅 atomic-examples/quickstart/quickstart/ 目录中的以下文件：

• 基础聊天机器人 - 一个最小化的聊天机器人示例，助您入门。
• 自定义聊天机器人 - 一个更高级的示例，包含自定义系统提示。
• 带模式的自定义聊天机器人 - 一个高级示例，展示了自定义输出模式。
• 多提供商聊天机器人 - 演示如何使用不同的提供商，如 Ollama 或 Groq。

完整示例

除了快速入门示例外，我们还有更复杂的示例展示 Atomic Agents 的强大功能：

• 钩子系统：全面演示 AtomicAgent 钩子系统，用于监控、错误处理和性能指标，并具备智能重试机制。
• 基础多模态：演示如何结合文本分析图像，重点使用 GPT-4 Vision 功能提取营养标签的结构化信息。
• 深度研究：展示如何执行深度研究任务的高级示例。
• 编排智能体：展示如何创建一个编排智能体，根据用户输入智能地决定使用不同的工具（搜索或计算器）。
• RAG 聊天机器人：使用检索增强生成（RAG）实现上下文感知响应的聊天机器人。
• 网络搜索智能体：一个执行网络搜索并根据结果回答问题的智能智能体。
• YouTube 摘要器：从 YouTube 视频中提取并总结知识的智能体。
• YouTube 食谱提取：从烹饪视频中提取结构化食谱信息的示例，演示复杂的信息提取和结构化。

有关完整示例列表，请参见 examples 目录。

🚀 版本 2.0 发布！

观看：Atomic Agents V2.0 新功能

Atomic Agents v2.0 现已发布，带来重大改进！ 此版本包含一些破坏性更改，但显著改善了开发者体验：

v2.0 的关键变更：

• 更清晰的导入：移除了导入路径中的 .lib
• 重命名类：BaseAgent → AtomicAgent、BaseAgentConfig → AgentConfig 等
• 更好的类型安全：工具和智能体使用泛型类型参数
• 增强的流式处理：新增 run_stream() 和 run_async_stream() 方法
• 改进的组织结构：更优的模块结构，包含 context、connectors 等

⚠️ 从 v1.x 升级

如果您正在从 v1.x 升级，请阅读我们的综合升级指南以获取详细的迁移说明。

Atomic Forge 与 CLI

Atomic Forge 是一组可与 Atomic Agents 配合使用的工具集合，用于扩展其功能。当前工具包括：

• 计算器
• SearXNG 搜索
• YouTube 字幕提取器

有关使用和创建工具的更多信息，请参见 Atomic Forge README。

运行 CLI

要运行 CLI，只需执行以下命令：

atomic

或者，如果您从克隆的仓库使用 uv 运行：

uv run atomic

运行此命令后，您将看到一个菜单，允许您下载工具。

每个工具都有自己独立的：

• 输入模式
• 输出模式
• 使用示例
• 依赖项
• 安装说明

atomic-assembler CLI 为您提供对工具的完全控制，避免不必要的依赖混乱。它使修改工具变得简单直接，此外，每个工具都附带一组测试以确保可靠性。

但您不仅仅局限于 CLI！ 如果您愿意，可以直接访问工具文件夹并手动管理，只需复制粘贴即可。

项目结构

Atomic Agents 采用单体仓库结构，包含以下主要组件：

1. atomic-agents/：核心 Atomic Agents 库
2. atomic-assembler/：管理 Atomic Agents 组件的 CLI 工具
3. atomic-examples/：展示 Atomic Agents 使用的示例项目
4. atomic-forge/：可与 Atomic Agents 配合使用的工具集合

对于本地开发，您可以从仓库安装：

git clone https://github.com/BrainBlend-AI/atomic-agents.git
cd atomic-agents
uv sync

要安装所有工作区包（示例和工具）：

uv sync --all-packages

提供商与模型兼容性

Atomic Agents 依赖于 Instructor 包。这意味着在所有使用 OpenAI 的示例中，Instructor 支持的任何其他 API 也可以使用——例如 Ollama、Groq、Mistral、Cohere、Anthropic、Gemini、MiniMax 等。有关完整列表，请参阅 Instructor 文档的 GitHub 页面。

贡献

我们欢迎贡献！请参阅贡献指南了解如何为 Atomic Agents 做出贡献的详细信息。以下是一些快速步骤：

1. Fork 仓库
2. 创建新分支 (git checkout -b feature-branch)
3. 进行更改
4. 运行测试 (uv run pytest --cov=atomic_agents atomic-agents)
5. 格式化代码 (uv run black atomic-agents atomic-assembler atomic-examples atomic-forge)
6. 检查代码风格 (uv run flake8 --extend-exclude=.venv atomic-agents atomic-assembler atomic-examples atomic-forge)
7. 提交更改 (git commit -m '添加某个功能')
8. 推送到分支 (git push origin feature-branch)
9. 创建 pull request

有关完整的开发设置和指南，请参阅开发者指南。

许可证

本项目采用 MIT 许可证——详情请参见 LICENSE 文件。

其他资源

如果您想了解更多关于 Atomic Agents 背后的动机和理念，我建议阅读这篇 Medium 文章（无需账号）。

视频资源：
- 观看概述视频 - 了解框架的理念和设计原则
- 观看快速入门视频 - 通过代码示例快速入门

星标历史