Imagine building AI applications as effortlessly as assembling LEGO blocks. That’s the idea behind Atomic Agents, a modular framework for constructing AI agents inspired by Atomic Design principles. With the release of version 2.0, Atomic Agents has matured based on real-world production usage, featuring cleaner imports, better type safety, and enhanced streaming capabilities while maintaining the powerful Atomic Assembler CLI that makes it even easier to build, manage, and deploy your AI applications.

Why Atomic Agents?

Many existing frameworks for Agentic AI focus on building autonomous multi-agent systems that are more like curiosities than practical tools. While these can be fascinating, they often lack the predictability and control required for real-world applications.

Businesses typically aren’t looking for a bot that writes articles in a different style each time. They want consistency in style, structure, and tone to align with their brand identity. Fine-tuning a model is one approach, but it requires substantial data and resources, and it’s not always feasible with the latest models.

Atomic Agents aims to solve this by providing:

• Modularity: Build complex AI systems by combining simple, interchangeable components.

• Atomicity: Each component within Atomic Agents, each tool, each agent, each context provider, is as single-purpose and re-usable as possible, Guaranteeing a great separation of concerns.

• Control: Fine-tune each individual step and component, from system prompts to tools.

• Predictability: Ensure reproducible and reliable outputs suitable for business use cases.

• Extensibility: Easily add or replace components without overhauling the entire system.

A Traditional Modular Approach

In traditional software development, complex problems are broken down into smaller, manageable parts:

1. Define the problem: Start with flows, user stories, or customer journeys.

2. Break it down: Divide the problem into smaller, solvable tasks.

3. Develop modular code: Write functions or classes that handle specific tasks.

4. Integrate: Combine these modules to form the complete application.

Atomic Agents brings this same level of modularity and predictability to AI agent development.

A Real-World Scenario

Instead of building a monolithic AI system that “writes a blog post,” we can design a modular system that:

1. Generates queries related to a subject.

2. Identifies the top X most relevant articles.

3. Visits each identified article’s page.

4. Extracts the text from each article.

5. Generates summaries of each article.

6. Stores the summaries in a vector database.

7. Generates questions around the subject.

8. Answers those questions using the vector database.

9. Synthesizes the answers into a coherent blog post.

This approach is more verbose but offers greater control, reliability, and suitability for real-world business applications.

Introduction of the CLI: Atomic Assembler

One of the significant additions in version 1.0 is the Atomic Assembler CLI. This command-line tool allows you to:

• Download and manage tools: Easily add new tools or agents to your project.

• Avoid unnecessary dependencies: Install only what you need.

• Modify tools effortlessly: Each tool comes with its own tests and documentation.

• Access tools directly: If you prefer, manage tools manually without the CLI.

Anatomy of an Agent

AI agents, especially in the Atomic Agents framework, consist of several key components:

• System Prompt: Defines the agent’s behavior and purpose.

• User Input: The data provided by the user.

• Tools: External functions or APIs the agent can utilize.

• Memory: Keeps track of the conversation or state.

Each component is designed to be modular and interchangeable, adhering to the principles of separation of concerns and single responsibility.

The Power of Modularity

By breaking down agents into these atomic components, you can:

• Swap out tools without affecting the rest of the system.

• Fine-tune prompts to adjust the agent’s behavior.

• Chain agents and tools seamlessly by matching their input and output schemas.

Using the CLI: Atomic Assembler

Installation

To get started with Atomic Agents and the CLI, install the package via pip:

pip install atomic-agents

Running the CLI

Launch the CLI using:

atomic

Or, if you installed Atomic Agents with Poetry:

poetry run atomic

You’ll be presented with a menu to download and manage tools:

Each tool includes:

• Input Schema

• Output Schema

• Usage Examples

• Dependencies

• Installation Instructions

Managing Tools

The Atomic Assembler CLI provides complete control over your tools, allowing you to:

• Avoid dependency clutter: Install only the tools you need.

• Modify tools easily: Each tool is self-contained with its own tests.

• Access tools directly: Manage tool folders manually if you prefer.

Context Providers

Atomic Agents introduces Context Providers to enhance your agents with dynamic context. Context Providers allow you to inject additional information into the agent’s system prompt at runtime.

Using Context Providers

Create a Context Provider Class: Subclass BaseDynamicContextProvider and implement the get_info() method.

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)

Register the Context Provider with the Agent:

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

This allows your agent to include dynamic data like search results in its system prompt, enhancing its responses based on the latest information.

Chaining Schemas and Agents

Atomic Agents simplifies chaining agents and tools by aligning their input and output schemas. This design promotes modularity and reusability.

Example: Generating Queries for Different Search Providers

Suppose you have an agent that generates search queries and you want to use these queries with different search tools. By aligning the agent’s output schema with the input schema of the search tool, you can easily chain them or switch between providers.

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

Modularity: By using type parameters where the agent’s output schema matches the input_schema of SearxNGSearchTool, you can directly use the output of the agent as input to the tool. The type system ensures compatibility at compile time.

Swapability: To switch to a different search provider, create a new agent instance with the appropriate type parameters:

from web_search_agent.tools.another_search import AnotherSearchTool

query_agent_v2 = AtomicAgent[QueryAgentInputSchema, AnotherSearchTool.input_schema](
    AgentConfig(
        # Same configuration as before
    )
)

Example: Building a Simple AI Agent

Now that we’ve covered the basics, let’s build a simple AI agent using Atomic Agents and explore how it works under the hood.

Step 1: Installation

First, install the necessary packages:

pip install atomic-agents openai instructor

Step 2: Import Components

Import the necessary components:

import os
from typing import List

import instructor
import openai
from pydantic import Field

from atomic_agents import AtomicAgent, AgentConfig, BaseIOSchema
from atomic_agents.context import ChatHistory, SystemPromptGenerator

Step 3: Define Custom Schemas

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

Step 4: Set Up the System Prompt

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

Step 5: Initialize the Agent

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

Step 6: Use the Agent

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

What’s Happening Behind the Scenes?

• System Prompt: Defines the agent’s behavior and guides the LLM.

• Input Schema: Validates the user’s input (now defined as a type parameter).

• Output Schema: Ensures the agent’s response matches the expected format (also a type parameter).

• Chat History: Keeps track of the conversation history (renamed from Memory for clarity).

• Type Safety: Generic type parameters provide better IDE support and compile-time checking.

Conclusion

Atomic Agents 2.0 brings enhanced modularity, control, and flexibility to AI agent development. With cleaner imports, better type safety through generic parameters, explicit streaming methods, and the powerful Atomic Assembler CLI, building sophisticated AI applications has never been easier or more reliable.

The framework has matured based on real-world production usage, with improvements like:

• Cleaner import paths without the .lib directory

• Type-safe agents and tools using Python 3.12+ type parameters

• Clear distinction between streaming and non-streaming operations

• Better naming conventions (AtomicAgent, ChatHistory, BaseDynamicContextProvider)

• Enhanced async support with dedicated streaming methods

Whether you’re a developer aiming to build AI-powered tools or a business looking to automate complex tasks, Atomic Agents provides the building blocks to create reliable, type-safe, and maintainable AI systems.

Get Started Today

• GitHub Repository: BrainBlend-AI/atomic-agents

• API Documentation: Atomic Agents API Docs

• Examples Directory: Atomic Examples