atomic-agents

Atomic Agents

What is Atomic Agents?

The Atomic Agents framework is designed around the concept of atomicity to be an extremely lightweight and modular framework for building Agentic AI pipelines and applications without sacrificing developer experience and maintainability.

Think of it like building AI applications with LEGO blocks - each component (agent, tool, context provider) is:

• Single-purpose: Does one thing well
• Reusable: Can be used in multiple pipelines
• Composable: Easily combines with other components
• Predictable: Produces consistent, reliable outputs

Built on Instructor and Pydantic, it enables you to create AI applications with the same software engineering principles you already know and love.

NEW: Join our community on Discord at discord.gg/J3W9b5AZJR and our official subreddit at /r/AtomicAgents!

Table of Contents

• Atomic Agents
  • What is Atomic Agents?
  • Table of Contents
  • Getting Started
    • Installation
    • Quick Example
  • Why Atomic Agents?
  • Core Concepts
    • Anatomy of an Agent
    • Context Providers
    • Chaining Schemas and Agents
  • Examples & Documentation
    • Quickstart Examples
    • Complete Examples
  • AI-Assisted Development
    • Project instructions (Cursor, Windsurf, Cline, Continue, and Aider)
    • Agent skills (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, ...)
    • Docs for LLMs
  • 🚀 Version 2.0 Released!
    • Key Changes in v2.0:
    • ⚠️ Upgrading from v1.x
  • Atomic Forge & CLI
    • Running the CLI
  • Project Structure
  • Provider & Model Compatibility
  • Support
  • Contributing
  • License
  • Additional Resources
  • Star History

Getting Started

Installation

To install Atomic Agents, you can use pip:

pip install atomic-agents

Make sure you also install the provider you want to use. Provider SDKs are available as instructor extras:

pip install instructor[groq]        # for Groq
pip install instructor[anthropic]   # for Anthropic
pip install instructor[google-genai] # for Gemini

OpenAI is included by default. For a full list of supported providers, see the Instructor docs.

This also installs the CLI Atomic Assembler, which can be used to download Tools (and soon also Agents and Pipelines).

Quick Example

Here's a quick snippet demonstrating how easy it is to create a powerful agent with Atomic Agents:

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

# Define a custom output schema
class CustomOutputSchema(BaseIOSchema):
    """
    docstring for the custom output schema
    """
    chat_message: str = Field(..., description="The chat message from the agent.")
    suggested_questions: list[str] = Field(..., description="Suggested follow-up questions.")

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

# Initialize OpenAI client
client = instructor.from_openai(OpenAI())

# Initialize the agent
agent = AtomicAgent[BasicChatInputSchema, CustomOutputSchema](
    config=AgentConfig(
        client=client,
        model="gpt-5-mini",
        system_prompt_generator=system_prompt_generator,
        history=ChatHistory(),
    )
)

# Example usage
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}")

Why Atomic Agents?

While existing frameworks for agentic AI focus on building autonomous multi-agent systems, they often lack the control and predictability required for real-world applications. Businesses need AI systems that produce consistent, reliable outputs aligned with their brand and objectives.

Atomic Agents addresses this need by providing:

• Modularity: Build AI applications by combining small, reusable components.
• Predictability: Define clear input and output schemas to ensure consistent behavior.
• Extensibility: Easily swap out components or integrate new ones without disrupting the entire system.
• Control: Fine-tune each part of the system individually, from system prompts to tool integrations.

All logic and control flows are written in Python, enabling developers to apply familiar best practices and workflows from traditional software development without compromising flexibility or clarity.

Core Concepts

Anatomy of an Agent

In Atomic Agents, an agent is composed of several key components:

• System Prompt: Defines the agent's behavior and purpose.
• Input Schema: Specifies the structure and validation rules for the agent's input.
• Output Schema: Specifies the structure and validation rules for the agent's output.
• History: Stores conversation history or other relevant data.
• Context Providers: Inject dynamic context into the agent's system prompt at runtime.

Here's a high-level architecture diagram:

Context Providers

Atomic Agents allows you to enhance your agents with dynamic context using Context Providers. Context Providers enable you to inject additional information into the agent's system prompt at runtime, making your agents more flexible and context-aware.

To use a Context Provider, create a class that inherits from BaseDynamicContextProvider and implements the get_info() method, which returns the context string to be added to the system prompt.

Here's a simple example:

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)

You can then register your Context Provider with the agent:

# Initialize your context provider with dynamic data
search_results_provider = SearchResultsProvider(
    title="Search Results",
    search_results=["Result 1", "Result 2", "Result 3"]
)

# Register the context provider with the agent
agent.register_context_provider("search_results", search_results_provider)

This allows your agent to include the search results (or any other context) in its system prompt, enhancing its responses based on the latest information.

Chaining Schemas and Agents

Atomic Agents makes it easy to chain agents and tools together by aligning their input and output schemas. This design allows you to swap out components effortlessly, promoting modularity and reusability in your AI applications.

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 together or switch between different search providers.

Here's how you can achieve this: