Atomic Agents

// Overview

Atomic Agents is a lightweight, modular Python framework for building agentic AI pipelines and applications. It is built on top of Instructor and Pydantic, so you define typed input and output schemas and get structured, validated responses from the language model instead of raw free text.

The framework is organized around atomicity: each piece, whether an agent, tool, or context provider, is single-purpose, reusable, and composable, like LEGO blocks. Its focus is control and predictability, which makes it a fit for developers who want consistent outputs and the ability to fine-tune each part of the system individually.

It belongs to the agent-frameworks category and is aimed at Python developers who prefer to keep all logic and control flow in plain Python code, applying familiar software engineering practices rather than handing control to an autonomous multi-agent system.

// What it does

• Schema-driven agents: define Pydantic input and output schemas so the model returns structured, validated data
• Built on Instructor and Pydantic for typed responses and standard Python validation
• Composable building blocks: combine single-purpose agents, tools, and context providers into pipelines
• Context Providers inject dynamic information into the system prompt at runtime
• SystemPromptGenerator builds structured prompts from background, steps, and output instructions
• Ships with the Atomic Assembler CLI for downloading tools, and works with multiple model providers via Instructor extras (OpenAI, Anthropic, Groq, Gemini)

// Getting started

Install the package with pip, install the provider SDK you want, then build a typed agent and call run().

pip install atomic-agents

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

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

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(),
    )
)

response = agent.run(BasicChatInputSchema(chat_message="Tell me about atomic agents framework"))
print(response.chat_message)

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Building chat assistants that must return structured, validated fields (for example a message plus suggested follow-up questions) rather than free text
• Assembling multi-step AI pipelines from small, reusable agents and tools where each step has a clear input and output schema
• Injecting dynamic, runtime context (such as user data or search results) into an agent's prompt via Context Providers
• Teams that want predictable, controllable agent behavior aligned with a brand or product instead of fully autonomous agents

// How Atomic Agents compares

Atomic Agents alongside other open-source agent frameworks & builders tools AI/TLDR tracks, ranked by GitHub stars.