Atomic Agents

What does this agent do, and when should you use it?

Atomic Agents is a lightweight Python framework for composing agents, tools, and context providers into agentic AI pipelines. Its core library supplies AtomicAgent, AgentConfig, typed I/O schemas, SystemPromptGenerator, ChatHistory, and dynamic-context interfaces, with Pydantic and Instructor handling structured outputs. Developers write the control flow in Python, so the framework runs inside an application or service rather than acting as a standalone hosted agent. The monorepo also includes the atomic-assembler component CLI, atomic-examples, and the atomic-forge tool collection. OpenAI is included by default, while Instructor provides documented paths to Anthropic, Gemini, Groq, Ollama, Mistral, Cohere, and OpenAI-compatible APIs. It fits teams that prioritize explicit orchestration, reusable components, and validated outputs, provided they are prepared to own deployment and production workflow design.

An application defines input and output contracts as Pydantic models derived from BaseIOSchema, describes behavior through SystemPromptGenerator, and passes an Instructor client, model, prompt generator, and optional ChatHistory into AgentConfig. AtomicAgent.run() accepts typed input, calls the configured model API, and returns an object constrained by the selected output schema. Runtime information can be injected into the system prompt by implementing BaseDynamicContextProvider.get_info() and attaching the provider with register_context_provider(). Agents and tools can be chained by making one component's output schema match the next component's input schema; the documented query-agent example targets SearXNGSearchTool.input_schema directly. The installed atomic CLI opens Atomic Assembler, which downloads selected Atomic Forge tools. Listed tools cover arXiv, BoCha, Hacker News, SearXNG, Tavily, Wikipedia, weather, PDF reading, webpage scraping, YouTube transcripts, date and time, and calculation, while repository examples cover chat, image extraction, research, RAG, web search, tool routing, and video-to-structured-data workflows.

1. A Python backend team can require model responses to match Pydantic fields before passing them into business logic.
2. An engineer building a search or research pipeline can chain query generation, a SearXNG-style search tool, and answer generation through compatible schemas.
3. A RAG application team can implement BaseDynamicContextProvider to inject retrieved material into an agent's system prompt at runtime.
4. A project that may change model vendors can preserve its agents and schemas while replacing the Instructor client for OpenAI, Anthropic, Gemini, Groq, Ollama, or a compatible API.
5. A prototype developer can use Atomic Assembler to download only the search, PDF, weather, or YouTube tools needed by the application.
6. A production engineering team can use the Hooks System example as a basis for monitoring, performance metrics, error handling, and retry behavior.

How do you install or deploy this agent?

You need Python, network access, and valid credentials for the chosen model provider. The supplied material does not state a minimum Python version or prescribe credential environment-variable names. OpenAI support is included with the default package:

pip install atomic-agents

Install the appropriate Instructor extra for another provider:

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

For local development from source:

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

To install every workspace package, including examples and tools:

uv sync --all-packages

How do you use this agent?

Configure credentials as required by the selected provider SDK; the supplied material does not specify an exact environment variable. This documented OpenAI pattern sends a message and prints a schema-validated response plus three follow-up questions:

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}")

Launch the installed Atomic Assembler menu to download tools:

atomic

From a cloned repository managed with uv, run:

uv run atomic

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

1. v2.12.0 2026-10-15
   Release notes excerpt

   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. …

   View on GitHub ↗
2. v2.11.0 2026-10-15
   Release notes excerpt

   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) …

   View on GitHub ↗
3. v2.10.3 2026-09-27
   Release notes excerpt

   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 …

   View on GitHub ↗

FAQ