Skip to content

Building AI agents, atomically

Improve README

KennyVaneetvelde5fe7833e0157
diff --git a/README.md b/README.md
index 30c0517..0b74846 100644
--- a/README.md
+++ b/README.md
@@ -13,105 +13,49 @@
[![GitHub Stars](https://img.shields.io/github/stars/BrainBlend-AI/atomic-agents?style=social)](https://github.com/BrainBlend-AI/atomic-agents/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/BrainBlend-AI/atomic-agents?style=social)](https://github.com/BrainBlend-AI/atomic-agents/network/members)
-## Table of Contents
+## What is Atomic Agents?
-- [Atomic Agents](#atomic-agents)
- - [Table of Contents](#table-of-contents)
- - [Overview](#overview)
- - [🚀 Version 2.0 Released!](#-version-20-released)
- - [Key Changes in v2.0:](#key-changes-in-v20)
- - [⚠️ Upgrading from v1.x](#️-upgrading-from-v1x)
- - [Documentation](#documentation)
- - [Watch the Overview Video](#watch-the-overview-video)
- - [Watch the Quickstart Video](#watch-the-quickstart-video)
- - [Why Atomic Agents?](#why-atomic-agents)
- - [Anatomy of an Agent](#anatomy-of-an-agent)
- - [Installation](#installation)
- - [Project Structure](#project-structure)
- - [Quickstart \& Examples](#quickstart--examples)
- - [Context Providers](#context-providers)
- - [Using Context Providers](#using-context-providers)
- - [Chaining Schemas and Agents](#chaining-schemas-and-agents)
- - [Example: Generating Queries for Different Search Providers](#example-generating-queries-for-different-search-providers)
- - [Running the CLI](#running-the-cli)
- - [Provider \& Model Compatibility](#provider--model-compatibility)
- - [Atomic Forge](#atomic-forge)
- - [Contributing](#contributing)
- - [License](#license)
- - [Star History](#star-history)
+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.
-## Overview
+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
-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. The framework provides a set of tools and agents that can be combined to create powerful applications. It is built on top of [Instructor](https://github.com/jxnl/instructor) and leverages the power of [Pydantic](https://docs.pydantic.dev/latest/) for data and schema validation and serialization.
-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.
+Built on [Instructor](https://github.com/jxnl/instructor) and [Pydantic](https://docs.pydantic.dev/latest/), 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](https://discord.gg/J3W9b5AZJR) and our official subreddit at [/r/AtomicAgents](https://www.reddit.com/r/AtomicAgents/)!**
-## 🚀 Version 2.0 Released!
-
-**Atomic Agents v2.0 is here with major improvements!** This release includes breaking changes that significantly improve the developer experience:
-
-### Key Changes in v2.0:
-- **Cleaner imports**: Eliminated `.lib` from import paths
-- **Renamed classes**: `BaseAgent` → `AtomicAgent`, `BaseAgentConfig` → `AgentConfig`, and more
-- **Better type safety**: Generic type parameters for tools and agents
-- **Enhanced streaming**: New `run_stream()` and `run_async_stream()` methods
-- **Improved organization**: Better module structure with `context`, `connectors`, and more
-
-### ⚠️ Upgrading from v1.x
-If you're upgrading from v1.x, please read our comprehensive [**Upgrade Guide**](UPGRADE_DOC.md) for detailed migration instructions.
-
-## Documentation
-
-[![Read the Docs](https://img.shields.io/badge/docs-read%20the%20docs-blue?logo=readthedocs&style=for-the-badge)](https://brainblend-ai.github.io/atomic-agents/)
-
-> 🚀 Ready to explore our documentation? Dive in below!
-
-[Visit the Documentation Site »](https://brainblend-ai.github.io/atomic-agents/)
-
-If you want to learn more about the motivation and philosophy behind Atomic Agents, [I suggest reading this Medium article (no account needed)](https://ai.gopubby.com/want-to-build-ai-agents-c83ab4535411?sk=b9429f7c57dbd3bda59f41154b65af35) or check out the overview video below:
-
-### [Watch the Overview Video](https://www.youtube.com/watch?v=Sp30YsjGUW0)
-<a href="https://www.youtube.com/watch?v=Sp30YsjGUW0" target="_blank">
- <img src="./.assets/video-thumbnail-1.png" alt="Watch the video" width="350"/>
-</a>
-
----
-
-If you just want to dive into the code straight away, I suggest checking out the quickstart video below:
-
-### [Watch the Quickstart Video](https://www.youtube.com/watch?v=CyZxRU0ax3Q)
-<a href="https://www.youtube.com/watch?v=CyZxRU0ax3Q" target="_blank">
- <img src="./.assets/video-thumbnail-2.png" alt="Watch the video" width="350"/>
-</a>
-
----
-
-## 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.
-
-## Anatomy of an Agent
-In Atomic Agents, an agent is composed of several key components:
+## Table of Contents
-- **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.
+- [What is Atomic Agents?](#what-is-atomic-agents)
+- [Getting Started](#getting-started)
+ - [Installation](#installation)
+ - [Quick Example](#quick-example)
+- [Why Atomic Agents?](#why-atomic-agents)
+- [Core Concepts](#core-concepts)
+ - [Anatomy of an Agent](#anatomy-of-an-agent)
+ - [Context Providers](#context-providers)
+ - [Chaining Schemas and Agents](#chaining-schemas-and-agents)
+- [Examples & Documentation](#examples--documentation)
+ - [Quickstart Examples](#quickstart-examples)
+ - [Complete Examples](#complete-examples)
+- [🚀 Version 2.0 Released!](#-version-20-released)
+ - [Key Changes in v2.0:](#key-changes-in-v20)
+ - [⚠️ Upgrading from v1.x](#️-upgrading-from-v1x)
+- [Atomic Forge & CLI](#atomic-forge--cli)
+ - [Running the CLI](#running-the-cli)
+- [Project Structure](#project-structure)
+- [Provider \& Model Compatibility](#provider--model-compatibility)
+- [Contributing](#contributing)
+- [License](#license)
+- [Additional Resources](#additional-resources)
+- [Star History](#star-history)
-Here's a high-level architecture diagram:
-<!-- ![alt text](./.assets/architecture_highlevel_overview.png) -->
-<img src="./.assets/architecture_highlevel_overview.png" alt="High-level architecture overview of Atomic Agents" width="600"/>
-<img src="./.assets/what_is_sent_in_prompt.png" alt="Diagram showing what is sent to the LLM in the prompt" width="600"/>
+## Getting Started
-## Installation
+### Installation
To install Atomic Agents, you can use pip:
```bash
@@ -126,27 +70,7 @@ pip install openai groq
This also installs the CLI *Atomic Assembler*, which can be used to download Tools (and soon also Agents and Pipelines).
-For local development, you can install from the repository:
-
-```bash
-git clone https://github.com/BrainBlend-AI/atomic-agents.git
-cd atomic-agents
-poetry install
-```
-
-## Project Structure
-
-Atomic Agents uses a monorepo structure with the following main components:
-
-1. `atomic-agents/`: The core Atomic Agents library
-2. `atomic-assembler/`: The CLI tool for managing Atomic Agents components
-3. `atomic-examples/`: Example projects showcasing Atomic Agents usage
-4. `atomic-forge/`: A collection of tools that can be used with Atomic Agents
-
-## Quickstart & Examples
-A complete list of examples can be found in the [examples](./atomic-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.
+### Quick Example
Here's a quick snippet demonstrating how easy it is to create a powerful agent with Atomic Agents:
@@ -202,46 +126,38 @@ if __name__ == "__main__":
print(f"- {question}")
```
-This snippet showcases how to create a customizable agent that responds to user queries and suggests follow-up questions. For full, runnable examples, please refer to the following files in the `atomic-examples/quickstart/quickstart/` directory:
-
-- [Basic Chatbot](/atomic-examples/quickstart/quickstart/1_basic_chatbot.py)
- A minimal chatbot example to get you started.
-
-- [Custom Chatbot](/atomic-examples/quickstart/quickstart/2_basic_custom_chatbot.py)
- A more advanced example with a custom system prompt.
-
-- [Custom Chatbot with Schema](/atomic-examples/quickstart/quickstart/3_basic_custom_chatbot_with_custom_schema.py)
- An advanced example featuring a custom output schema.
-
-- [Multi-Provider Chatbot](/atomic-examples/quickstart/quickstart/4_basic_chatbot_different_providers.py)
- Demonstrates how to use different providers such as Ollama or Groq.
-
-In addition to the quickstart examples, we have more complex examples demonstrating the power of Atomic Agents:
-
-- [Basic Multimodal](/atomic-examples/basic-multimodal/README.md): Demonstrates how to analyze images with text, focusing on extracting structured information from nutrition labels using GPT-4 Vision capabilities.
-
-- [Deep Research](/atomic-examples/deep-research/README.md): An advanced example showing how to perform deep research tasks.
+## 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.
-- [Orchestration Agent](/atomic-examples/orchestration-agent/README.md): Shows how to create an Orchestrator Agent that intelligently decides between using different tools (search or calculator) based on user input.
+Atomic Agents addresses this need by providing:
-- [RAG Chatbot](/atomic-examples/rag-chatbot/README.md): A chatbot implementation using Retrieval-Augmented Generation (RAG) to provide context-aware responses.
+- **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.
-- [Web Search Agent](/atomic-examples/web-search-agent/README.md): An intelligent agent that performs web searches and answers questions based on the results.
+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.
-- [YouTube Summarizer](/atomic-examples/youtube-summarizer/README.md): An agent that extracts and summarizes knowledge from YouTube videos.
+## Core Concepts
-- [YouTube to Recipe](/atomic-examples/youtube-to-recipe/README.md): An example that extracts structured recipe information from cooking videos, demonstrating complex information extraction and structuring.
+### Anatomy of an Agent
+In Atomic Agents, an agent is composed of several key components:
-For a complete list of examples, see the [examples directory](/atomic-examples/).
+- **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.
-These examples provide a great starting point for understanding and using Atomic Agents.
+Here's a high-level architecture diagram:
+<!-- ![alt text](./.assets/architecture_highlevel_overview.png) -->
+<img src="./.assets/architecture_highlevel_overview.png" alt="High-level architecture overview of Atomic Agents" width="600"/>
+<img src="./.assets/what_is_sent_in_prompt.png" alt="Diagram showing what is sent to the LLM in the prompt" width="600"/>
-## Context Providers
+### 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.
-### Using Context Providers
-
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:
@@ -273,12 +189,10 @@ 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
+### 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.
-### Example: Generating Queries for Different Search Providers
-
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:
@@ -339,7 +253,62 @@ 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.
-## Running the CLI
+## Examples & Documentation
+
+[![Read the Docs](https://img.shields.io/badge/docs-read%20the%20docs-blue?logo=readthedocs&style=for-the-badge)](https://brainblend-ai.github.io/atomic-agents/)
+
+[Visit the Documentation Site »](https://brainblend-ai.github.io/atomic-agents/)
+
+### Quickstart Examples
+
+A complete list of examples can be found in the [examples](./atomic-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:
+
+- [Basic Chatbot](/atomic-examples/quickstart/quickstart/1_basic_chatbot.py) - A minimal chatbot example to get you started.
+- [Custom Chatbot](/atomic-examples/quickstart/quickstart/2_basic_custom_chatbot.py) - A more advanced example with a custom system prompt.
+- [Custom Chatbot with Schema](/atomic-examples/quickstart/quickstart/3_basic_custom_chatbot_with_custom_schema.py) - An advanced example featuring a custom output schema.
+- [Multi-Provider Chatbot](/atomic-examples/quickstart/quickstart/4_basic_chatbot_different_providers.py) - Demonstrates how to use different providers such as Ollama or Groq.
+
+### Complete Examples
+
+In addition to the quickstart examples, we have more complex examples demonstrating the power of Atomic Agents:
+
+- [Basic Multimodal](/atomic-examples/basic-multimodal/README.md): Demonstrates how to analyze images with text, focusing on extracting structured information from nutrition labels using GPT-4 Vision capabilities.
+- [Deep Research](/atomic-examples/deep-research/README.md): An advanced example showing how to perform deep research tasks.
+- [Orchestration Agent](/atomic-examples/orchestration-agent/README.md): Shows how to create an Orchestrator Agent that intelligently decides between using different tools (search or calculator) based on user input.
+- [RAG Chatbot](/atomic-examples/rag-chatbot/README.md): A chatbot implementation using Retrieval-Augmented Generation (RAG) to provide context-aware responses.
+- [Web Search Agent](/atomic-examples/web-search-agent/README.md): An intelligent agent that performs web searches and answers questions based on the results.
+- [YouTube Summarizer](/atomic-examples/youtube-summarizer/README.md): An agent that extracts and summarizes knowledge from YouTube videos.
+- [YouTube to Recipe](/atomic-examples/youtube-to-recipe/README.md): An example that extracts structured recipe information from cooking videos, demonstrating complex information extraction and structuring.
+
+For a complete list of examples, see the [examples directory](/atomic-examples/).
+
+## 🚀 Version 2.0 Released!
+
+**Atomic Agents v2.0 is here with major improvements!** This release includes breaking changes that significantly improve the developer experience:
+
+### Key Changes in v2.0:
+- **Cleaner imports**: Eliminated `.lib` from import paths
+- **Renamed classes**: `BaseAgent` → `AtomicAgent`, `BaseAgentConfig` → `AgentConfig`, and more
+- **Better type safety**: Generic type parameters for tools and agents
+- **Enhanced streaming**: New `run_stream()` and `run_async_stream()` methods
+- **Improved organization**: Better module structure with `context`, `connectors`, and more
+
+### ⚠️ Upgrading from v1.x
+If you're upgrading from v1.x, please read our comprehensive [**Upgrade Guide**](UPGRADE_DOC.md) for detailed migration instructions.
+
+## Atomic Forge & CLI
+
+Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
+
+- Calculator
+- SearXNG Search
+- YouTube Transcript Scraper
+
+For more information on using and creating tools, see the [Atomic Forge README](/atomic-forge/README.md).
+
+### Running the CLI
To run the CLI, simply run the following command:
@@ -377,19 +346,26 @@ The `atomic-assembler` CLI gives you complete control over your tools, avoiding
![Atomic CLI menu](./.assets/atomic-cli.png)
-## Provider & Model Compatibility
+## Project Structure
-Atomic Agents depends on the [Instructor](https://github.com/jxnl/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](https://github.com/jxnl/instructor).
+Atomic Agents uses a monorepo structure with the following main components:
-## Atomic Forge
+1. `atomic-agents/`: The core Atomic Agents library
+2. `atomic-assembler/`: The CLI tool for managing Atomic Agents components
+3. `atomic-examples/`: Example projects showcasing Atomic Agents usage
+4. `atomic-forge/`: A collection of tools that can be used with Atomic Agents
-Atomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:
+For local development, you can install from the repository:
-- Calculator
-- SearXNG Search
-- YouTube Transcript Scraper
+```bash
+git clone https://github.com/BrainBlend-AI/atomic-agents.git
+cd atomic-agents
+poetry install
+```
-For more information on using and creating tools, see the [Atomic Forge README](/atomic-forge/README.md).
+## Provider & Model Compatibility
+
+Atomic Agents depends on the [Instructor](https://github.com/jxnl/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](https://github.com/jxnl/instructor).
## Contributing
@@ -411,6 +387,14 @@ For full development setup and guidelines, please refer to the [Developer Guide]
This project is licensed under the MIT License—see the [LICENSE](LICENSE) file for details.
+## Additional Resources
+
+If you want to learn more about the motivation and philosophy behind Atomic Agents, [I suggest reading this Medium article (no account needed)](https://ai.gopubby.com/want-to-build-ai-agents-c83ab4535411?sk=b9429f7c57dbd3bda59f41154b65af35).
+
+**Video Resources:**
+- [Watch the Overview Video](https://www.youtube.com/watch?v=Sp30YsjGUW0) - Learn about the framework's philosophy and design principles
+- [Watch the Quickstart Video](https://www.youtube.com/watch?v=CyZxRU0ax3Q) - Get started with code examples
+
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=BrainBlend-AI/atomic-agents&type=Date)](https://star-history.com/#BrainBlend-AI/atomic-agents&Date)