Atomic Agents

这个 Agent 能做什么，适合哪些场景？

Atomic Agents 是一个轻量级 Python 框架，用于把代理、工具和上下文提供器组合成 Agentic AI 流程。核心库提供 AtomicAgent、AgentConfig、输入输出 Schema、SystemPromptGenerator、ChatHistory 和动态上下文接口，并借助 Pydantic 与 Instructor 生成和校验结构化结果。控制流由开发者直接用 Python 编写，而不是交给自主多代理系统，因此部署边界是嵌入开发者自己的 Python 应用或服务。仓库采用 monorepo，包含核心库 atomic-agents、组件下载 CLI atomic-assembler、示例项目 atomic-examples 和工具集合 atomic-forge。它支持 OpenAI，并可通过 Instructor 接入 Anthropic、Gemini、Groq、Ollama、Mistral、Cohere 及 OpenAI 兼容 API。适合重视类型约束、模块复用和显式流程控制的团队，但使用者仍需自行设计业务编排、部署方式和错误处理策略。

应用先用继承自 BaseIOSchema 的 Pydantic 模型定义输入和输出，再通过 SystemPromptGenerator 配置背景、步骤和输出要求，并把 Instructor 客户端、模型、提示词生成器及可选的 ChatHistory 传给 AgentConfig。AtomicAgent.run() 接收类型化输入，调用所配置的模型 API，并返回经过目标 Schema 约束的结构化对象。运行时数据可由继承 BaseDynamicContextProvider 且实现 get_info() 的组件注入系统提示词；上下文提供器通过 register_context_provider() 注册。不同代理和工具可通过对齐输出 Schema 与下一组件的输入 Schema 串联，例如让查询生成代理直接产出 SearXNGSearchTool.input_schema。随包安装的 atomic CLI 可浏览和下载 Atomic Forge 工具；仓库列出的工具覆盖 arXiv、BoCha、Hacker News、SearXNG、Tavily、Wikipedia、天气、PDF、网页、YouTube 字幕、日期时间和计算等操作。示例还展示聊天、图像信息提取、深度研究、RAG、网页搜索、工具路由和视频内容结构化。

1. Python 后端团队需要让模型输出经过 Pydantic 校验的固定字段，以便安全地交给后续业务代码处理。
2. 开发搜索或研究流程的工程师，需要把查询生成代理、SearXNG 等搜索工具和答案生成步骤按 Schema 串联。
3. 构建 RAG 聊天应用的团队，需要通过 BaseDynamicContextProvider 在运行时把检索结果注入系统提示词。
4. 需要切换模型供应商的项目，可保留代理和 Schema 设计，同时通过 Instructor 改接 OpenAI、Anthropic、Gemini、Groq、Ollama 或兼容 API。
5. 原型开发者希望从 Atomic Forge 选择并下载单个搜索、PDF、天气或 YouTube 工具，而不安装整套工具依赖。
6. 需要监控和重试能力的工程团队，可参考仓库中的 Hooks System 示例构建错误处理与性能指标流程。

如何安装或部署这个 Agent？

需要 Python、网络访问以及所选模型供应商的有效凭据；来源没有规定 Python 最低版本，也没有给出凭据环境变量名称。OpenAI 支持随默认安装提供：

pip install atomic-agents

如使用其他供应商，还需安装对应的 Instructor extra：

pip install instructor[groq]
pip install instructor[anthropic]
pip install instructor[google-genai]

从源码进行本地开发：

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

安装 monorepo 中的全部工作区包、示例和工具：

uv sync --all-packages

如何使用这个 Agent？

先按所选供应商的 SDK 要求配置凭据；来源未给出具体环境变量。下面是文档中的 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

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

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."
    ]
)

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 = "Tell me about atomic agents framework"
    response = agent.run(BasicChatInputSchema(chat_message=user_input))
    print(f"Agent: {response.chat_message}")
    print("Suggested questions:")
    for question in response.suggested_questions:
        print(f"- {question}")

安装后可启动 Atomic Assembler 菜单下载工具：

atomic

在克隆的仓库中也可通过 uv 启动：

uv run atomic

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v2.12.0 2026-10-15
   发布说明摘录

   Released 2026-10-15. Firecrawl Search, FXMacroData and Phoenix tracing shipped earlier the same day in 2.11.0. Changes - Discover every page of MCP tools, resources and prompts. Propagate template continuation errors instead of silently dropping them. - Resolve MCP schema references to non-object definitions and decode escaped definition names. - Parse JSON text from real MCP SDK results when structured content is absent. Preserve precedence for present structured content, including empty values. …

   在 GitHub 查看 ↗
2. v2.11.0 2026-10-15
   发布说明摘录

   What's New Arize Phoenix / OpenInference tracing Atomic Agents now ships an optional OpenInference instrumentor. Install atomic-agents[observability] (or just have arize-phoenix-otel installed) and phoenix.otel.register(auto_instrument=True) picks it up automatically. Features - AGENT span per AtomicAgent.run / run_async / run_stream / run_async_stream, named Class[InputSchema, OutputSchema].run, with input/output JSON and atomic_agents.* attributes (model, mode, schema names, history size, context providers, static prompt hash) …

   在 GitHub 查看 ↗
3. v2.10.3 2026-09-27
   发布说明摘录

   What's New Bug Fixes - ChatHistory.copy() no longer serializes and re-imports message classes, so an agent can be created with a history that contains schemas defined inside a function or factory (#288, thanks @YaoxinHuang) - MCP tools with nullable fields ({"type": ["string", "null"]}) no longer disappear from discovery; type arrays resolve to unions and null maps to None instead of Any (#283, thanks @Shy7777) Atomic Forge - New serply_search tool: Google web, News and Scholar search through the Serply API (#284, thanks @googio) Full Changelog …

   在 GitHub 查看 ↗

常见问题