# Atomic Agents

> Build AI agents from small, schema-driven blocks for predictable output

- Category: Agents & Automation / Agent Frameworks & Builders
- Language: Python
- Licence: MIT
- Repository: https://github.com/Eigenwise/atomic-agents
- Website: https://brainblend-ai.github.io/atomic-agents/
- Canonical page: https://ai-tldr.dev/tools/atomic-agents/

## In short

Atomic Agents is a lightweight, modular Python framework for building agentic AI pipelines and applications. It sits in the Agent Frameworks & Builders category of the Agents & Automation tools and is open-source, written in Python and licensed MIT. To get started: install 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().

1. Install Atomic Agents

   Install the framework with pip. This also installs the Atomic Assembler CLI for downloading tools.

```bash
pip install atomic-agents
```

2. Install a model provider

   Provider SDKs come as Instructor extras. OpenAI is included by default; install others as needed.

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

3. Create and run an agent

   Define an output schema, set up a system prompt, wrap your model client with Instructor, and call run() with a typed input.

```python
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)
```

## 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