介绍 Atomic Agents 2.0 — 面向企业与生产环境的 AI Agent 构建方案

想象一下，构建 AI 应用就像组装乐高积木一样轻松。这正是 Atomic Agents 的设计理念------一个受"原子设计"（Atomic Design）原则启发、用于构建 AI Agent 的模块化框架。随着 2.0 版本的发布，Atomic Agents 基于真实生产环境的使用经验完成了迭代优化，不仅保留了功能强大的 Atomic Assembler 命令行工具（CLI），让 AI 应用的构建、管理和部署变得更加便捷，还实现了更简洁的导入方式、更优的类型安全性（type safety）以及增强的流处理能力。

本指南的核心内容与 Atomic Agents 1.0 版本的指南基本一致，但已更新以体现最新新增的特性，包括类型安全性、可控制性、可调试性以及整体开发者体验的优化。

为何选择 Atomic Agents？

目前许多现有的 Agentic AI 框架，重心都放在构建自主式多 Agent 系统上------这类系统更偏向于"新奇技术演示"，而非实用工具。尽管它们可能极具吸引力，但往往缺乏真实应用场景所需的可预测性和可控性。

企业通常不需要"每次都用不同风格撰写文章"的机器人。它们需要的是风格、结构和语气上的一致性，以契合自身的品牌定位。对模型进行微调（Fine-tuning）是一种解决方案，但这种方式需要大量数据和资源支持，且对于 GPT-4.1 这类最新模型而言，并非总能实现。

Atomic Agents 旨在通过以下特性解决上述问题：

模块化（Modularity）：通过组合简单、可互换的组件，构建复杂的 AI 系统。
原子性（Atomicity）：Atomic Agents 中的每个组件------无论是工具、Agent 还是上下文提供器（context provider）------都尽可能实现"单一用途"和"可复用"，确保各功能模块的职责清晰分离。
可控性（Control）：对每个独立步骤和组件进行精细调整，范围涵盖系统提示（system prompts）到工具的各个层面。
可预测性（Predictability）：确保输出结果可复现、可靠，满足业务场景需求。
可扩展性（Extensibility）：无需全面重构整个系统，即可轻松添加或替换组件。

传统的模块化方法

在传统软件开发中，复杂问题会被拆解为更小、更易于管理的部分，具体步骤如下：

定义问题：从业务流程（flows）、用户故事（user stories）或客户旅程（customer journeys）入手。
拆解问题：将复杂问题拆分为更小、可解决的任务。
开发模块化代码：编写处理特定任务的函数或类。
集成：将这些模块组合起来，形成完整的应用。

Atomic Agents 将这种"模块化"与"可预测性"带入了 AI Agent 的开发领域。

真实场景案例

我们无需构建一个"撰写博客文章"的单体 AI 系统，而是可以设计一个模块化系统，该系统的工作流程如下：

生成与某一主题相关的查询词（queries）。
筛选出与主题最相关的前 X 篇文章。
访问每篇筛选出的文章页面。
提取每篇文章的文本内容。
为每篇文章生成摘要。
将摘要存储到向量数据库（vector database）中。
围绕该主题生成相关问题。
利用向量数据库回答这些问题。
将所有答案整合为一篇逻辑连贯的博客文章。

这种方法虽然流程更细致，但能提供更强的可控性和可靠性，更适合真实的企业业务场景。

CLI 介绍：Atomic Assembler

1.0 版本中一项重要新增功能便是 Atomic Assembler CLI。这款命令行工具支持你完成以下操作：

下载并管理工具：轻松向项目中添加新工具或 agent。
避免不必要的依赖：仅安装所需内容。
轻松修改工具：每个工具都附带专属测试用例和文档。
直接访问工具：若你倾向于不使用 CLI，也可手动管理工具。

Agent 的组成结构

AI agent（尤其是在 Atomic Agents 框架中）由多个关键组件构成：

系统提示（System Prompt）：定义 agent 的行为方式与核心用途。
用户输入（User Input）：用户提供的数据信息。
工具（Tools）：agent 可调用的外部函数或 API。
记忆（Memory）：记录对话内容或系统状态。

每个组件均采用模块化设计，支持灵活替换，遵循"关注点分离"与"单一职责"原则。

模块化的优势

通过将 agent 拆解为这些原子级组件，你可以：

替换工具，且不影响系统其他部分。
微调提示词，以调整 agent 的行为。
通过匹配输入与输出模式（schema），实现 agent 与工具的无缝串联。

CLI 使用指南：Atomic Assembler

安装步骤

若要开始使用 Atomic Agents 及 CLI，可通过 pip 安装该包：

sql 复制代码

pip install atomic-agents

运行 CLI

通过以下命令启动 CLI：

sql 复制代码

atomic

或者，若你通过 Poetry 安装了 Atomic Agents，可使用：

arduino 复制代码

poetry run atomic

此时会显示一个菜单，可用于下载和管理工具：

每个工具均包含以下内容：

输入模式（Input Schema）
输出模式（Output Schema）
使用示例（Usage Examples）
依赖项（Dependencies）
安装说明（Installation Instructions）

工具管理

Atomic Assembler CLI 提供了对工具的全面控制权，你可以：

避免依赖冗余：仅安装所需工具。
轻松修改工具：每个工具都是独立封装的，且附带专属测试。
直接访问工具：若你倾向于手动操作，也可直接管理工具文件夹。

上下文提供器（Context Providers）

Atomic Agents 引入了"上下文提供器（Context Providers）"，为你的 agent 增强动态上下文能力。通过 Context Providers，你可以在运行时向 agent 的系统提示中注入额外信息。

使用上下文提供器（Context Providers）

创建上下文提供器类：继承BaseDynamicContextProvider并实现get_info()方法。

python 复制代码

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)

向Agent注册上下文提供器：

ini 复制代码

search_results_provider = SearchResultsProvider(
    title="Search Results",
    search_results=["Result 1", "Result 2", "Result 3"]
)

agent.register_context_provider("search_results", search_results_provider)

这使你的Agent能够在系统提示中包含搜索结果等动态数据，基于最新信息增强其响应能力。

串联模式（Schemas）与Agent

Atomic Agents通过对齐Agent和工具的输入输出模式，简化了它们之间的串联流程。这种设计提升了模块化和可复用性。

示例：为不同搜索提供商生成查询词

假设你有一个生成搜索查询词的Agent，并且希望将这些查询词用于不同的搜索工具。通过让Agent的输出模式与搜索工具的输入模式对齐，你可以轻松地将它们串联起来，或在不同提供商之间切换。

python 复制代码

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

from web_search_agent.tools.searxng_search import SearxNGSearchTool

class QueryAgentInputSchema(BaseIOSchema):
    """Input schema for the QueryAgent."""
    instruction: str = Field(..., description="Instruction to generate search queries for.")
    num_queries: int = Field(..., description="Number of queries to generate.")

query_agent = AtomicAgent[QueryAgentInputSchema, SearxNGSearchTool.input_schema](
    AgentConfig(
        client=instructor.from_openai(openai.OpenAI()),
        model="gpt-4o",
        system_prompt_generator=SystemPromptGenerator(
            background=[
                "You are an intelligent query generation expert.",
                "Your task is to generate diverse and relevant queries based on a given instruction."
            ],
            steps=[
                "Receive the instruction and the number of queries.",
                "Generate the queries in JSON format."
            ],
            output_instructions=[
                "Ensure each query is unique and relevant.",
                "Provide the queries in the expected schema."
            ],
        )
    )
)

模块化 ：通过使用类型参数，使Agent的输出模式与SearxNGSearchTool的input_schema匹配，你可以直接将Agent的输出作为工具的输入。类型系统会在编译时确保兼容性。

可替换性：若要切换到不同的搜索提供商，只需创建一个带有适当类型参数的新Agent实例：

ini 复制代码

from web_search_agent.tools.another_search import AnotherSearchTool

query_agent_v2 = AtomicAgent[QueryAgentInputSchema, AnotherSearchTool.input_schema](
    AgentConfig(
        # 保持与之前相同的配置
    )
)

示例：构建一个简单的 AI Agent

现在我们已经介绍了基础知识，接下来让我们使用 Atomic Agents 构建一个简单的 AI Agent，并探究其底层工作原理。

步骤 1：安装

首先，安装必要的包：

sql 复制代码

pip install atomic-agents openai instructor

步骤 2：导入组件

导入所需组件：

javascript 复制代码

import os
from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema
from atomic_agents.context import ChatHistory, SystemPromptGenerator
from pydantic import Field
from typing import List
import instructor
import openai

步骤 3：定义自定义模式

ini 复制代码

class CustomInputSchema(BaseIOSchema):
    chat_message: str = Field(..., description="The user's message.")

class CustomOutputSchema(BaseIOSchema):
    chat_message: str = Field(..., description="The chat message from the agent.")
    suggested_questions: List[str] = Field(..., description="Suggested follow-up questions.")

步骤 4：设置系统提示

ini 复制代码

system_prompt_generator = SystemPromptGenerator(
    background=["This assistant is knowledgeable, helpful, and suggests follow-up questions."],
    steps=[
        "Analyze the user's input to understand the context and intent.",
        "Formulate a relevant and informative response.",
        "Generate 3 suggested follow-up questions for the user."
    ],
    output_instructions=[
        "Provide clear and concise information in response to user queries.",
        "Conclude each response with 3 relevant suggested questions for the user."
    ]
)

步骤 5：初始化 Agent

ini 复制代码

history = ChatHistory()

agent = AtomicAgent[CustomInputSchema, CustomOutputSchema](
    AgentConfig(
        client=instructor.from_openai(openai.OpenAI(api_key=os.getenv('OPENAI_API_KEY'))),
        model="gpt-4.1-mini",
        system_prompt_generator=system_prompt_generator,
        history=history,
        model_api_parameters={
            "temperature": 0.7,
            "max_tokens": 1000
        }
    )
)

步骤 6：使用 Agent

python 复制代码

user_input = "Can you explain the benefits of using Atomic Agents?"
response = agent.run(CustomInputSchema(chat_message=user_input))
print(f"Agent: {response.chat_message}")
print("Suggested questions:")
for question in response.suggested_questions:
    print(f"- {question}")

底层工作原理是什么？

系统提示（System Prompt）：定义 Agent 的行为方式，并为大语言模型（LLM）提供引导。
输入模式（Input Schema）：验证用户输入（现已定义为类型参数）。
输出模式（Output Schema）：确保 Agent 的响应符合预期格式（同样作为类型参数）。
对话历史（Chat History）：记录对话历史（为清晰起见，已从 Memory 重命名）。
类型安全性（Type Safety）：泛型类型参数提供更优的 IDE 支持和编译时检查。

结语

Atomic Agents 2.0 为 AI Agent 开发带来了更强的模块化、可控性和灵活性。借助更简洁的导入方式、通过泛型参数实现的更优类型安全性、明确的流处理方法以及功能强大的 Atomic Assembler CLI，构建复杂 AI 应用从未如此简单可靠。

该框架基于真实生产环境的使用经验完成迭代成熟，带来了多项改进，例如：

更简洁的导入路径，无需依赖 .lib 目录
利用 Python 3.12+ 类型参数实现的类型安全 Agent 和工具
明确区分流处理（streaming）与非流处理（non-streaming）操作
更清晰的命名规范（AtomicAgent、ChatHistory、BaseDynamicContextProvider）
通过专用流处理方法增强的异步（async）支持

无论你是希望构建 AI 驱动工具的开发者，还是寻求自动化复杂任务的企业，Atomic Agents 都能提供所需的构建模块，助力打造可靠、类型安全且易于维护的 AI 系统。