atomic-agents
Advanced tools
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. For example, to use OpenAI and Groq, you can install the openai and groq packages:
pip install openai groq
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:
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}")
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:
import instructor
import openai
from pydantic import Field
from atomic_agents import BaseIOSchema, AtomicAgent, AgentConfig
from atomic_agents.context import SystemPromptGenerator
# Import the search tool you want to use
from web_search_agent.tools.searxng_search import SearXNGSearchTool
# Define the input schema for the query agent
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.")
# Initialize the query agent
query_agent = AtomicAgent[QueryAgentInputSchema, SearXNGSearchTool.input_schema](
config=AgentConfig(
client=instructor.from_openai(openai.OpenAI()),
model="gpt-5-mini",
system_prompt_generator=SystemPromptGenerator(
background=[
"You are an intelligent query generation expert.",
"Your task is to generate a specified number of diverse and highly relevant queries based on a given instruction."
],
steps=[
"Receive the instruction and the number of queries to generate.",
"Generate the queries in JSON format."
],
output_instructions=[
"Ensure each query is unique and relevant.",
"Provide the queries in the expected schema."
],
),
)
)
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.
Atomic Agents v2.0 is here with major improvements! This release includes breaking changes that significantly improve the developer experience:
.lib from import pathsBaseAgent → AtomicAgent, BaseAgentConfig → AgentConfig, and morerun_stream() and run_async_stream() methodscontext, connectors, and moreIf you're upgrading from v1.x, please read our comprehensive Upgrade Guide for detailed migration instructions.
Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
For more information on using and creating tools, see the Atomic Forge README.
To run the CLI, simply run the following command:
atomic
Or if you're running from a cloned repository with uv:
uv run atomic
After running this command, you will be presented with a menu allowing you to download tools.
Each tool's has its own:
The atomic-assembler CLI gives you complete control over your tools, avoiding the clutter of unnecessary dependencies. It makes modifying tools straightforward additionally, each tool comes with its own set of tests for reliability.
But you're not limited to the CLI! If you prefer, you can directly access the tool folders and manage them manually by simply copying and pasting as needed.
Atomic Agents uses a monorepo structure with the following main components:
atomic-agents/: The core Atomic Agents libraryatomic-assembler/: The CLI tool for managing Atomic Agents componentsatomic-examples/: Example projects showcasing Atomic Agents usageatomic-forge/: A collection of tools that can be used with Atomic AgentsFor local development, you can install from the repository:
git clone https://github.com/BrainBlend-AI/atomic-agents.git
cd atomic-agents
uv sync
To install all workspace packages (examples and tools):
uv sync --all-packages
Atomic Agents depends on the Instructor package. This means that in all examples where OpenAI is used, any other API supported by Instructor can also be used—such as Ollama, Groq, Mistral, Cohere, Anthropic, Gemini, and more. For a complete list, please refer to the Instructor documentation on its GitHub page.
We welcome contributions! Please see the Contributing Guide for detailed information on how to contribute to Atomic Agents. Here are some quick steps:
git checkout -b feature-branch)uv run pytest --cov=atomic_agents atomic-agents)uv run black atomic-agents atomic-assembler atomic-examples atomic-forge)uv run flake8 --extend-exclude=.venv atomic-agents atomic-assembler atomic-examples atomic-forge)git commit -m 'Add some feature')git push origin feature-branch)For full development setup and guidelines, please refer to the Developer Guide.
This project is licensed under the MIT License—see the LICENSE file for details.
If you want to learn more about the motivation and philosophy behind Atomic Agents, I suggest reading this Medium article (no account needed).
Video Resources:
FAQs
A versatile framework for creating and managing intelligent agents.
We found that atomic-agents demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
An emerging npm supply chain attack that infects repos, steals CI secrets, and targets developer AI toolchains for further compromise.
Company News
Socket is proud to join the OpenJS Foundation as a Silver Member, deepening our commitment to the long-term health and security of the JavaScript ecosystem.
Security News
npm now links to Socket's security analysis on every package page. Here's what you'll find when you click through.