# Atomic Agents
<img src="./.assets/logo.png" alt="Atomic Agents" width="350"/>
[](https://badge.fury.io/py/atomic-agents)
[](https://brainblend-ai.github.io/atomic-agents/)
[](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/docs.yml)
[](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/code-quality.yml)
[](https://discord.gg/J3W9b5AZJR)
[](https://pypi.org/project/atomic-agents/)
[](https://pypi.org/project/atomic-agents/)
[](LICENSE)
[](https://github.com/BrainBlend-AI/atomic-agents/stargazers)
[](https://github.com/BrainBlend-AI/atomic-agents/network/members)
## What is Atomic Agents?
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:
- **Single-purpose**: Does one thing well
- **Reusable**: Can be used in multiple pipelines
- **Composable**: Easily combines with other components
- **Predictable**: Produces consistent, reliable outputs
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/)!**
## Table of Contents
- [Atomic Agents](#atomic-agents)
- [What is Atomic Agents?](#what-is-atomic-agents)
- [Table of Contents](#table-of-contents)
- [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)
## Getting Started
### Installation
To install Atomic Agents, you can use pip:
```bash
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:
```bash
pip install openai groq
```
This also installs the CLI *Atomic Assembler*, which can be used to download Tools (and soon also Agents and Pipelines).
### Quick Example
Here's a quick snippet demonstrating how easy it is to create a powerful agent with Atomic Agents:
```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
# 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-4o-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}")
```
## 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.
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.
## Core Concepts
### Anatomy of an Agent
In Atomic Agents, an agent is composed of several key components:
- **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.
Here's a high-level architecture diagram:
<!--  -->
<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
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:
```python
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:
```python
# 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.
### 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.
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:
```python
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-4o-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:
- **Modularity**: By setting the `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.
- **Swapability**: If you decide to switch to a different search provider, you can import a different search tool and update the `output_schema` accordingly.
For instance, to switch to another search service:
```python
# 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.
## Examples & Documentation
[](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_0_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_0_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:
```bash
atomic
```
Or if you installed Atomic Agents with Poetry, for example:
```bash
poetry run atomic
```
Or if you installed Atomic Agents with uv:
```bash
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:
- Input schema
- Output schema
- Usage example
- Dependencies
- Installation instructions
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.
## 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
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
```
## 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
We welcome contributions! Please see the [Contributing Guide](/docs/contributing.md) for detailed information on how to contribute to Atomic Agents. Here are some quick steps:
1. Fork the repository
2. Create a new branch (`git checkout -b feature-branch`)
3. Make your changes
4. Run tests (`poetry run pytest --cov=atomic_agents atomic-agents`)
5. Format your code (`poetry run black atomic-agents atomic-assembler atomic-examples atomic-forge`)
6. Lint your code (`poetry run flake8 --extend-exclude=.venv atomic-agents atomic-assembler atomic-examples atomic-forge`)
7. Commit your changes (`git commit -m 'Add some feature'`)
8. Push to the branch (`git push origin feature-branch`)
9. Open a pull request
For full development setup and guidelines, please refer to the [Developer Guide](/guides/DEV_GUIDE.md).
## License
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
[](https://star-history.com/#BrainBlend-AI/atomic-agents&Date)
Raw data
{
"_id": null,
"home_page": null,
"name": "atomic-agents",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Kenny Vaneetvelde",
"author_email": "kenny.vaneetvelde@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/30/0f/fd38ea64716f64813610221139c6adfbaa45fc0d2e00973327df2e57f772/atomic_agents-2.0.5.tar.gz",
"platform": null,
"description": "# Atomic Agents\n\n<img src=\"./.assets/logo.png\" alt=\"Atomic Agents\" width=\"350\"/>\n\n[](https://badge.fury.io/py/atomic-agents)\n[](https://brainblend-ai.github.io/atomic-agents/)\n[](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/docs.yml)\n[](https://github.com/BrainBlend-AI/atomic-agents/actions/workflows/code-quality.yml)\n[](https://discord.gg/J3W9b5AZJR)\n[](https://pypi.org/project/atomic-agents/)\n[](https://pypi.org/project/atomic-agents/)\n[](LICENSE)\n[](https://github.com/BrainBlend-AI/atomic-agents/stargazers)\n[](https://github.com/BrainBlend-AI/atomic-agents/network/members)\n\n## What is Atomic Agents?\n\nThe 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.\n\nThink of it like building AI applications with LEGO blocks - each component (agent, tool, context provider) is:\n- **Single-purpose**: Does one thing well\n- **Reusable**: Can be used in multiple pipelines\n- **Composable**: Easily combines with other components\n- **Predictable**: Produces consistent, reliable outputs\n\nBuilt 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.\n\n**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/)!**\n\n## Table of Contents\n\n- [Atomic Agents](#atomic-agents)\n - [What is Atomic Agents?](#what-is-atomic-agents)\n - [Table of Contents](#table-of-contents)\n - [Getting Started](#getting-started)\n - [Installation](#installation)\n - [Quick Example](#quick-example)\n - [Why Atomic Agents?](#why-atomic-agents)\n - [Core Concepts](#core-concepts)\n - [Anatomy of an Agent](#anatomy-of-an-agent)\n - [Context Providers](#context-providers)\n - [Chaining Schemas and Agents](#chaining-schemas-and-agents)\n - [Examples \\& Documentation](#examples--documentation)\n - [Quickstart Examples](#quickstart-examples)\n - [Complete Examples](#complete-examples)\n - [\ud83d\ude80 Version 2.0 Released!](#-version-20-released)\n - [Key Changes in v2.0:](#key-changes-in-v20)\n - [\u26a0\ufe0f Upgrading from v1.x](#\ufe0f-upgrading-from-v1x)\n - [Atomic Forge \\& CLI](#atomic-forge--cli)\n - [Running the CLI](#running-the-cli)\n - [Project Structure](#project-structure)\n - [Provider \\& Model Compatibility](#provider--model-compatibility)\n - [Contributing](#contributing)\n - [License](#license)\n - [Additional Resources](#additional-resources)\n - [Star History](#star-history)\n\n## Getting Started\n\n### Installation\nTo install Atomic Agents, you can use pip:\n\n```bash\npip install atomic-agents\n```\n\nMake 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:\n\n```bash\npip install openai groq\n```\n\nThis also installs the CLI *Atomic Assembler*, which can be used to download Tools (and soon also Agents and Pipelines).\n\n### Quick Example\n\nHere's a quick snippet demonstrating how easy it is to create a powerful agent with Atomic Agents:\n\n```python\nfrom pydantic import Field\nfrom openai import OpenAI\nimport instructor\nfrom atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BaseIOSchema\nfrom atomic_agents.context import SystemPromptGenerator, ChatHistory\n\n# Define a custom output schema\nclass CustomOutputSchema(BaseIOSchema):\n \"\"\"\n docstring for the custom output schema\n \"\"\"\n chat_message: str = Field(..., description=\"The chat message from the agent.\")\n suggested_questions: list[str] = Field(..., description=\"Suggested follow-up questions.\")\n\n# Set up the system prompt\nsystem_prompt_generator = SystemPromptGenerator(\n background=[\"This assistant is knowledgeable, helpful, and suggests follow-up questions.\"],\n steps=[\n \"Analyze the user's input to understand the context and intent.\",\n \"Formulate a relevant and informative response.\",\n \"Generate 3 suggested follow-up questions for the user.\"\n ],\n output_instructions=[\n \"Provide clear and concise information in response to user queries.\",\n \"Conclude each response with 3 relevant suggested questions for the user.\"\n ]\n)\n\n# Initialize OpenAI client\nclient = instructor.from_openai(OpenAI())\n\n# Initialize the agent\nagent = AtomicAgent[BasicChatInputSchema, CustomOutputSchema](\n config=AgentConfig(\n client=client,\n model=\"gpt-4o-mini\",\n system_prompt_generator=system_prompt_generator,\n history=ChatHistory(),\n )\n)\n\n# Example usage\nif __name__ == \"__main__\":\n user_input = \"Tell me about atomic agents framework\"\n response = agent.run(BasicChatInputSchema(chat_message=user_input))\n print(f\"Agent: {response.chat_message}\")\n print(\"Suggested questions:\")\n for question in response.suggested_questions:\n print(f\"- {question}\")\n```\n\n## Why Atomic Agents?\nWhile 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.\n\nAtomic Agents addresses this need by providing:\n\n- **Modularity:** Build AI applications by combining small, reusable components.\n- **Predictability:** Define clear input and output schemas to ensure consistent behavior.\n- **Extensibility:** Easily swap out components or integrate new ones without disrupting the entire system.\n- **Control:** Fine-tune each part of the system individually, from system prompts to tool integrations.\n\nAll 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.\n\n## Core Concepts\n\n### Anatomy of an Agent\nIn Atomic Agents, an agent is composed of several key components:\n\n- **System Prompt:** Defines the agent's behavior and purpose.\n- **Input Schema:** Specifies the structure and validation rules for the agent's input.\n- **Output Schema:** Specifies the structure and validation rules for the agent's output.\n- **History:** Stores conversation history or other relevant data.\n- **Context Providers:** Inject dynamic context into the agent's system prompt at runtime.\n\nHere's a high-level architecture diagram:\n<!--  -->\n<img src=\"./.assets/architecture_highlevel_overview.png\" alt=\"High-level architecture overview of Atomic Agents\" width=\"600\"/>\n<img src=\"./.assets/what_is_sent_in_prompt.png\" alt=\"Diagram showing what is sent to the LLM in the prompt\" width=\"600\"/>\n\n### Context Providers\n\nAtomic 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.\n\nTo 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.\n\nHere's a simple example:\n\n```python\nfrom atomic_agents.context import BaseDynamicContextProvider\n\nclass SearchResultsProvider(BaseDynamicContextProvider):\n def __init__(self, title: str, search_results: List[str]):\n super().__init__(title=title)\n self.search_results = search_results\n\n def get_info(self) -> str:\n return \"\\n\".join(self.search_results)\n```\n\nYou can then register your Context Provider with the agent:\n\n```python\n# Initialize your context provider with dynamic data\nsearch_results_provider = SearchResultsProvider(\n title=\"Search Results\",\n search_results=[\"Result 1\", \"Result 2\", \"Result 3\"]\n)\n\n# Register the context provider with the agent\nagent.register_context_provider(\"search_results\", search_results_provider)\n```\n\nThis allows your agent to include the search results (or any other context) in its system prompt, enhancing its responses based on the latest information.\n\n### Chaining Schemas and Agents\n\nAtomic 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.\n\nSuppose 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.\n\nHere's how you can achieve this:\n\n```python\nimport instructor\nimport openai\nfrom pydantic import Field\nfrom atomic_agents import BaseIOSchema, AtomicAgent, AgentConfig\nfrom atomic_agents.context import SystemPromptGenerator\n\n# Import the search tool you want to use\nfrom web_search_agent.tools.searxng_search import SearXNGSearchTool\n\n# Define the input schema for the query agent\nclass QueryAgentInputSchema(BaseIOSchema):\n \"\"\"Input schema for the QueryAgent.\"\"\"\n instruction: str = Field(..., description=\"Instruction to generate search queries for.\")\n num_queries: int = Field(..., description=\"Number of queries to generate.\")\n\n# Initialize the query agent\nquery_agent = AtomicAgent[QueryAgentInputSchema, SearXNGSearchTool.input_schema](\n config=AgentConfig(\n client=instructor.from_openai(openai.OpenAI()),\n model=\"gpt-4o-mini\",\n system_prompt_generator=SystemPromptGenerator(\n background=[\n \"You are an intelligent query generation expert.\",\n \"Your task is to generate a specified number of diverse and highly relevant queries based on a given instruction.\"\n ],\n steps=[\n \"Receive the instruction and the number of queries to generate.\",\n \"Generate the queries in JSON format.\"\n ],\n output_instructions=[\n \"Ensure each query is unique and relevant.\",\n \"Provide the queries in the expected schema.\"\n ],\n ),\n )\n)\n```\n\nIn this example:\n\n- **Modularity**: By setting the `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.\n- **Swapability**: If you decide to switch to a different search provider, you can import a different search tool and update the `output_schema` accordingly.\n\nFor instance, to switch to another search service:\n\n```python\n# Import a different search tool\nfrom web_search_agent.tools.another_search import AnotherSearchTool\n\n# Update the output schema\nquery_agent.config.output_schema = AnotherSearchTool.input_schema\n```\n\nThis design pattern simplifies the process of chaining agents and tools, making your AI applications more adaptable and easier to maintain.\n\n## Examples & Documentation\n\n[](https://brainblend-ai.github.io/atomic-agents/)\n\n[Visit the Documentation Site \u00bb](https://brainblend-ai.github.io/atomic-agents/)\n\n### Quickstart Examples\n\nA 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.\n\nFor full, runnable examples, please refer to the following files in the `atomic-examples/quickstart/quickstart/` directory:\n\n- [Basic Chatbot](/atomic-examples/quickstart/quickstart/1_0_basic_chatbot.py) - A minimal chatbot example to get you started.\n- [Custom Chatbot](/atomic-examples/quickstart/quickstart/2_basic_custom_chatbot.py) - A more advanced example with a custom system prompt.\n- [Custom Chatbot with Schema](/atomic-examples/quickstart/quickstart/3_0_basic_custom_chatbot_with_custom_schema.py) - An advanced example featuring a custom output schema.\n- [Multi-Provider Chatbot](/atomic-examples/quickstart/quickstart/4_basic_chatbot_different_providers.py) - Demonstrates how to use different providers such as Ollama or Groq.\n\n### Complete Examples\n\nIn addition to the quickstart examples, we have more complex examples demonstrating the power of Atomic Agents:\n\n- [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.\n- [Deep Research](/atomic-examples/deep-research/README.md): An advanced example showing how to perform deep research tasks.\n- [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.\n- [RAG Chatbot](/atomic-examples/rag-chatbot/README.md): A chatbot implementation using Retrieval-Augmented Generation (RAG) to provide context-aware responses.\n- [Web Search Agent](/atomic-examples/web-search-agent/README.md): An intelligent agent that performs web searches and answers questions based on the results.\n- [YouTube Summarizer](/atomic-examples/youtube-summarizer/README.md): An agent that extracts and summarizes knowledge from YouTube videos.\n- [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.\n\nFor a complete list of examples, see the [examples directory](/atomic-examples/).\n\n## \ud83d\ude80 Version 2.0 Released!\n\n**Atomic Agents v2.0 is here with major improvements!** This release includes breaking changes that significantly improve the developer experience:\n\n### Key Changes in v2.0:\n- **Cleaner imports**: Eliminated `.lib` from import paths\n- **Renamed classes**: `BaseAgent` \u2192 `AtomicAgent`, `BaseAgentConfig` \u2192 `AgentConfig`, and more\n- **Better type safety**: Generic type parameters for tools and agents\n- **Enhanced streaming**: New `run_stream()` and `run_async_stream()` methods\n- **Improved organization**: Better module structure with `context`, `connectors`, and more\n\n### \u26a0\ufe0f Upgrading from v1.x\nIf you're upgrading from v1.x, please read our comprehensive [**Upgrade Guide**](UPGRADE_DOC.md) for detailed migration instructions.\n\n## Atomic Forge & CLI\n\nAtomic Forge is a collection of tools that can be used with Atomic Agents to extend its functionality. Current tools include:\n\n- Calculator\n- SearXNG Search\n- YouTube Transcript Scraper\n\nFor more information on using and creating tools, see the [Atomic Forge README](/atomic-forge/README.md).\n\n### Running the CLI\n\nTo run the CLI, simply run the following command:\n\n```bash\natomic\n```\n\nOr if you installed Atomic Agents with Poetry, for example:\n\n```bash\npoetry run atomic\n```\n\nOr if you installed Atomic Agents with uv:\n\n```bash\nuv run atomic\n```\n\nAfter running this command, you will be presented with a menu allowing you to download tools.\n\nEach tool's has its own:\n\n- Input schema\n- Output schema\n- Usage example\n- Dependencies\n- Installation instructions\n\n\n\nThe `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.\n\n**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.\n\n\n\n## Project Structure\n\nAtomic Agents uses a monorepo structure with the following main components:\n\n1. `atomic-agents/`: The core Atomic Agents library\n2. `atomic-assembler/`: The CLI tool for managing Atomic Agents components\n3. `atomic-examples/`: Example projects showcasing Atomic Agents usage\n4. `atomic-forge/`: A collection of tools that can be used with Atomic Agents\n\nFor local development, you can install from the repository:\n\n```bash\ngit clone https://github.com/BrainBlend-AI/atomic-agents.git\ncd atomic-agents\npoetry install\n```\n\n## Provider & Model Compatibility\n\nAtomic 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\u2014such 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).\n\n## Contributing\n\nWe welcome contributions! Please see the [Contributing Guide](/docs/contributing.md) for detailed information on how to contribute to Atomic Agents. Here are some quick steps:\n\n1. Fork the repository\n2. Create a new branch (`git checkout -b feature-branch`)\n3. Make your changes\n4. Run tests (`poetry run pytest --cov=atomic_agents atomic-agents`)\n5. Format your code (`poetry run black atomic-agents atomic-assembler atomic-examples atomic-forge`)\n6. Lint your code (`poetry run flake8 --extend-exclude=.venv atomic-agents atomic-assembler atomic-examples atomic-forge`)\n7. Commit your changes (`git commit -m 'Add some feature'`)\n8. Push to the branch (`git push origin feature-branch`)\n9. Open a pull request\n\nFor full development setup and guidelines, please refer to the [Developer Guide](/guides/DEV_GUIDE.md).\n\n## License\n\nThis project is licensed under the MIT License\u2014see the [LICENSE](LICENSE) file for details.\n\n## Additional Resources\n\nIf 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).\n\n**Video Resources:**\n- [Watch the Overview Video](https://www.youtube.com/watch?v=Sp30YsjGUW0) - Learn about the framework's philosophy and design principles\n- [Watch the Quickstart Video](https://www.youtube.com/watch?v=CyZxRU0ax3Q) - Get started with code examples\n\n## Star History\n\n[](https://star-history.com/#BrainBlend-AI/atomic-agents&Date)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A versatile framework for creating and managing intelligent agents.",
"version": "2.0.5",
"project_urls": {
"Homepage": "https://github.com/BrainBlend-AI/atomic-agents",
"Repository": "https://github.com/BrainBlend-AI/atomic-agents"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bc122b0c03713810399a13e76b48801ba5762be9d4d2931fe782f7dfff2b0257",
"md5": "2f1c05781720ec089431b963b80f6b6f",
"sha256": "bcb8bf665fd24d8dce9f7c7464df1ae03132de7fe2f90508a67e1e949c1c6122"
},
"downloads": -1,
"filename": "atomic_agents-2.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f1c05781720ec089431b963b80f6b6f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 50922,
"upload_time": "2025-08-24T08:30:48",
"upload_time_iso_8601": "2025-08-24T08:30:48.514310Z",
"url": "https://files.pythonhosted.org/packages/bc/12/2b0c03713810399a13e76b48801ba5762be9d4d2931fe782f7dfff2b0257/atomic_agents-2.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "300ffd38ea64716f64813610221139c6adfbaa45fc0d2e00973327df2e57f772",
"md5": "f839e8c7c98f51bd7a8696ca1f4d5bfa",
"sha256": "4c727f46fe087d418246fd8b493a8fca1ee685dd263adfd482846a88091bc452"
},
"downloads": -1,
"filename": "atomic_agents-2.0.5.tar.gz",
"has_sig": false,
"md5_digest": "f839e8c7c98f51bd7a8696ca1f4d5bfa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 36651,
"upload_time": "2025-08-24T08:30:50",
"upload_time_iso_8601": "2025-08-24T08:30:50.063007Z",
"url": "https://files.pythonhosted.org/packages/30/0f/fd38ea64716f64813610221139c6adfbaa45fc0d2e00973327df2e57f772/atomic_agents-2.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 08:30:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BrainBlend-AI",
"github_project": "atomic-agents",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "instructor",
"specs": [
[
">=",
"1.9.0"
],
[
"<",
"2.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.10.3"
]
]
},
{
"name": "rich",
"specs": [
[
"<",
"14.0.0"
],
[
">=",
"13.7.1"
]
]
},
{
"name": "gitpython",
"specs": [
[
"<",
"4.0.0"
],
[
">=",
"3.1.43"
]
]
},
{
"name": "pyfiglet",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.0.2"
]
]
},
{
"name": "textual",
"specs": [
[
"<",
"1.0.0"
],
[
">=",
"0.82.0"
]
]
},
{
"name": "pyyaml",
"specs": [
[
">=",
"6.0.2"
],
[
"<",
"7.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.32.3"
]
]
},
{
"name": "atomic-agents",
"specs": [
[
">=",
"1.0.0"
],
[
"<",
"2.0.0"
]
]
}
],
"lcname": "atomic-agents"
}
JSON
