Building AI agents, atomically
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:
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!
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).
Here's a quick snippet demonstrating how easy it is to create a powerful agent with 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:
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.
In Atomic Agents, an agent is composed of several key components:
Here's a high-level architecture diagram:
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.
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:
…
In this example:
output_schema of the query_agent to match the input_schema of SearXNGSearchTool, you can directly use the output of the agent as input to the tool.output_schema accordingly.For instance, to switch to another search service:
# Import a different search tool
from web_search_agent.tools.another_search import AnotherSearchTool
# Update the output schema
query_agent.config.output_schema = AnotherSearchTool.input_schema
This design pattern simplifies the process of chaining agents and tools, making your AI applications more adaptable and easier to maintain.
Visit the Documentation Site »
A complete list of examples can be found in the examples directory. We strive to thoroughly document each example, but if something is unclear, please don't hesitate to open an issue or pull request to improve the documentation.
For full, runnable examples, please refer to the following files in the atomic-examples/quickstart/quickstart/ directory:
In addition to the quickstart examples, we have more complex examples demonstrating the power of Atomic Agents:
For a complete list of examples, see the examples directory.
Building with an AI coding assistant? Atomic Agents ships first-class support so your assistant knows the framework's current API and conventions instead of guessing.
The root AGENTS.md is the canonical source of repository guidance. Each supported assistant receives that guidance through its native project-instruction mechanism:
| Assistant | Project configuration |
|---|---|
| Cursor | Reads AGENTS.md natively when this repository is opened as the workspace root. |
| Windsurf / Devin Desktop | Reads AGENTS.md through its Rules engine. |
| Cline | Detects AGENTS.md as a supported rule type. |
| Continue 2.0+ | Reads the root AGENTS.md natively as an always-on project instruction. |
| Aider | .aider.conf.yml loads AGENTS.md as a read-only conventions file. |
These files configure assistants working on the Atomic Agents repository itself. To add Atomic Agents framework knowledge to another project, install the agent skills below.
Six agent skills cover the framework: an auto-triggering framework guide with
No open issues yet, or sync has not completed.