How brainblend-ai/atomic-agents works
Project Type and Purpose
• Project type: A Python‐based, open‐source, modular AI‐agent framework delivered as a monorepo.
• Purpose: Provide a lightweight, composable “atomic” framework for building AI agents and pipelines, plus a CLI (“Atomic Assembler”) for installing and managing tools, a suite of example applications, and a curated tool registry (“Atomic Forge”).
File Structure
Top‐level directories:
• atomic-agents/ – Core library
• atomic-assembler/ – CLI application
• atomic-examples/ – Sample projects
• atomic-forge/ – Curated tool implementations
• docs/ & guides/ – Documentation site and developer guide
• scripts/, setup.py, pyproject.toml, requirements.txt – Build, CI, packaging
Inside atomic-agents/:
• atomic_agents/agents – BaseAgent classes & configs
• atomic_agents/lib/components – SystemPromptGenerator, AgentMemory, Context Providers
• atomic_agents/lib/factories – Tool‐factory, schema transformers
• atomic_agents/lib/utils – Message formatting
• tests/ – Unit tests for agents, components, factories, utils
atomic-assembler/:
• app.py, main.py – CLI entrypoints
• screens/, widgets/ – TUI layers (menus, explorers)
• utils.py, color_utils.py – CLI helpers
atomic-examples/:
• Subfolders for specific use cases (quickstart, RAG, orchestration, multimodal, etc.)
atomic-forge/:
• tools/ – Individual tool packages (calculator, searxng_search, etc.)
• Each tool: own tests, pyproject.toml, implementation
Extract Architectural Insights from README
• Core library (atomic-agents) is framework that wires together:
– System prompts
– Input/output schemas (Pydantic)
– Memory components
– Context Providers
– Agent execution via Instructor clients (OpenAI, Groq, etc.)
– Plugin tooling via atomic-forge
• CLI (atomic-assembler) is a menu‐based interface to download and scaffold tools/agents.
• Examples demonstrate typical pipelines: multi‐provider chatbots, RAG, orchestration, web search, summarization.
a. Main Components
1. Presentation / UX Layer
– atomic-assembler CLI (menus, file explorers, interactive screens)
– Example scripts / entrypoints in atomic-examples/
2. Core Framework (atomic-agents)
– BaseAgent & BaseIOSchema
– SystemPromptGenerator & ContextProviders
– AgentMemory
– Factories (ToolFactory, SchemaTransformer)
– Utils (format_tool_message)
3. Tool Registry (atomic-forge)
– Tools implementing input_schema, output_schema, perform()
4. External Services
– LLM Providers via Instructor (OpenAI, Groq, Anthropic, etc.)
– Third‐party APIs (search engines, web scraping endpoints)
5. Data Models & Storage
– Pydantic models for schema validation
– In‐memory conversation history (AgentMemory)
– Optional: external storage (not shown in tree)
b. Relationships & Data Flows
• User invokes CLI or runs an example → CLI/Script calls BaseAgent.run()
• BaseAgent assembles prompt via SystemPromptGenerator + registered ContextProviders + Memory
• Agent sends prompt to LLM client (Instructor) and receives response
• Response parsed into Output Schema (Pydantic)
• Optionally, agent invokes Tools from atomic-forge via ToolFactory → Tool input schema → external API call → return output schema → integrated into agent’s next step
• AgentMemory records conversation turns for future context
• Example scripts chain multiple agents/tools by matching output_schema to next input_schema
c. Architectural Patterns & Principles
– Modular / Plugin Architecture: core framework + external tools + context providers
– Factory Pattern: decouple tool instantiation (MCP Tool Factory, Schema Transformer)
– Dependency Inversion: abstract LLM client (Instructor) behind BaseAgentConfig.client
– Schema‐Driven Design: enforce strict input/output contracts via Pydantic
– Monorepo for cohesive distribution of library, CLI, examples, and tools
d. Key Technologies & Frameworks
– Python 3.x
– Pydantic for schema validation
– Instructor library as LLM client abstraction
– Poetry / pyproject.toml & setup.py for packaging
– pytest for testing
– Typer or a similar TUI library in atomic-assembler (menus/widgets)
– GitHub Actions for CI (code‐quality, docs generation)
Final Advice
– Capture both static structure (modules and packages) and dynamic flow (runtime prompt assembly and execution).