Eigenwise/atomic-agents · 上手攻略

仓库：Eigenwise/atomic-agents
链接：https://github.com/Eigenwise/atomic-agents
分类：ai
作者：Jay
更新：2026-07-12

是什么

atomic-agents 是一个以"原子化"为设计哲学的轻量级模块化 Agent 框架，基于 Instructor 和 Pydantic 构建。所有 Agent 组件（Agent、Tool、Context Provider）均为单一职责、可复用、可组合的"原子"单元，通过标准化的输入/输出 Schema 将它们像乐高积木一样拼装成完整 AI 应用，MIT 许可证。

解决什么问题

现有 Agent 框架常见痛点：

黑箱性：Agent 输出不可预测，缺乏结构化约束，企业场景无法接受。
紧耦合：组件之间依赖强，换一个模型或工具需要大幅重构。
调试困难：运行时行为不透明，出问题难以定位。
过度复杂：很多框架引入大量抽象，学习曲线陡峭。

atomic-agents 的核心理念是：用 Python 写 Agent 逻辑，用 Pydantic 约束输入输出，让 AI 应用享有传统软件工程的确定性和可维护性，同时保留灵活性。

快速安装

pip install atomic-agents

# 按需安装 LLM provider SDK（OpenAI 默认已含）
pip install instructor[groq]       # Groq
pip install instructor[anthropic]  # Anthropic
pip install instructor[google-genai] # Google Gemini

注意：Instructor 的 extras 命名与上游同步，如 instructor[groq] 而非 instructor[openai]（OpenAI 是默认内置）。

核心用法

最小示例

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

# 定义自定义输出 Schema
class CustomOutputSchema(BaseIOSchema):
    chat_message: str = Field(..., description="Agent 回复消息")
    suggested_questions: list[str] = Field(..., description="建议后续问题列表")

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

# 初始化客户端（Instructor 增强的 OpenAI）
client = instructor.from_openai(OpenAI())

# 创建 Agent
agent = AtomicAgent[BasicChatInputSchema, CustomOutputSchema](
    config=AgentConfig(
        client=client,
        model="gpt-5-mini",   # 建议用 gpt-4o 或 claude 系列
        system_prompt_generator=system_prompt_generator,
        history=ChatHistory(),
    )
)

# 运行
response = agent.run(BasicChatInputSchema(chat_message="Tell me about atomic agents"))
print(response.chat_message)
for q in response.suggested_questions:
    print(f"- {q}")

核心概念

1. Schema 驱动（BaseIOSchema）

所有 Agent 输入/输出均为 Pydantic Model，天然支持： - 类型验证（自动拒绝不合规输出） - LLM 结构化输出（Instructor 集成） - 单元测试（直接 assert） - 文档生成（Schema 即文档）

from atomic_agents import BaseIOSchema

class MyInput(BaseIOSchema):
    user_query: str = Field(..., description="用户查询")

class MyOutput(BaseIOSchema):
    answer: str = Field(..., description="回答")
    confidence: float = Field(..., description="置信度 0~1")

2. Context Provider（动态上下文注入）

在运行时向 Agent 系统提示注入动态内容，无需修改 Agent 本身：

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
provider = SearchResultsProvider(
    title="Search Results",
    search_results=["Result 1", "Result 2"]
)
agent.register_context_provider("search_results", provider)

3. Agent / Tool 链式组合

通过对齐输入/输出 Schema，实现组件无缝替换：

# 假设 SearchTool.input_schema = {"query": str, "limit": int}
# 只需让 QueryAgent.output_schema = SearchTool.input_schema
query_agent = AtomicAgent[QueryInput, SearchTool.input_schema](...)

# 运行时：query_agent 的输出直接作为 SearchTool 的输入
result = query_agent.run(QueryInput(instruction="latest AI news", num_queries=3))
search_result = search_tool.run(result)  # 输出类型匹配，无缝衔接

Atomic Forge（CLI 内置工具集）

官方提供开箱即用的工具集，通过 CLI 安装：

# 列出可用工具
atomic-assembler list-tools

# 安装单个工具
atomic-assembler install-tool arxiv_search
atomic-assembler install-tool searxng_search

内置工具包括：arXiv 搜索、计算器、日期时间、Fía 信号、Hacker News 搜索、PDF 阅读器、SearXNG 搜索、Tavily 搜索、网页抓取、天气、维基百科搜索、YouTube 转录等。

典型适用场景

企业级 RAG Chatbot：Schema 约束输出格式，确保回复结构稳定，便于后端处理。
多步骤研究 Agent：多个原子 Agent 串联（查询→搜索→摘要→整理），每步独立可测。
结构化数据抽取：PDF/文档中的实体、关系抽取，Pydantic Model 直接定义目标 Schema。
多 Provider 切换：同一套代码在 Groq / Anthropic / Gemini / Ollama 之间切换，无需改业务逻辑。
Deep Research：Chain of Agents 模式，多轮上下文注入，实现深度研究任务。

坑与注意

依赖 Instructor：atomic-agents 基于 Instructor 做结构化输出，Instructor 本身对各 LLM Provider 的支持成熟度不同，OpenAI 最稳定，其他 Provider 建议先用 --smoke-test 类机制验证。
Python 3.12+：项目明确要求 Python 3.12 及以上，低版本不兼容。
Schema 设计的质量决定输出质量：LLM 输出严格遵循 Pydantic Schema，但 Schema 描述（description）若模糊，模型理解偏差会导致输出不合规。description 应精确描述每个字段的语义和格式要求。
v1 → v2 升级有 Breaking Change：官方已发布 v2.0，升级文档中列出了具体 Breaking Change，v1 用户需仔细阅读迁移指南。
Hook 系统（v2 新增）：提供了监控、重试、错误处理钩子，但文档尚在完善，部分高级用法可能需要读源码。
CLI 工具集（Atomic Forge）：部分工具（如 Tavily 搜索）需要对应 API Key，按量计费。
Model 名称：示例中用 gpt-5-mini 等名称，2026 年中模型命名可能已有变化，建议以实际 Provider 文档为准。

与同类对比

框架	核心定位	Schema 约束	学习曲线	许可证
atomic-agents	原子化模块 Agent 框架	Pydantic 原生	⭐ 低	MIT
LangChain	通用 LLM 应用框架	较弱（LCEL 链式）	中	Apache 2.0
LlamaIndex	数据中心 RAG 框架	较弱	中	MIT
CrewAI	多 Agent 协作	较弱	⭐ 低	Apache 2.0
AutoGen	多 Agent 对话框架	无	中	MIT
Instructor	结构化输出（底层依赖）	Pydantic（底层）	低	Apache 2.0

atomic-agents 的差异化在于最彻底的 Schema-first 设计和原子级模块化——每个组件职责单一，组合成本极低。相比 LangChain 的 LCEL 链式抽象，它更接近传统 Python 风格，上手门槛更低，适合需要可预测输出的企业场景。

一句话推荐结论

atomic-agents 是目前最"Pythonic"的轻量 Agent 框架，Pydantic 原生集成让输出可预测、组件可测试，推荐需要构建企业级可控 AI 应用的开发者作为首选框架。