Atomic Agents

2.7.4 · active · verified Tue Mar 24

Lightweight agent framework by BrainBlend-AI built on top of instructor and pydantic. Focuses on typed, composable agents with explicit schemas. v2.0 introduced major breaking changes: all class renames, .lib removed from import paths, generic type parameters added. Current version: 2.7.4 (Mar 2026). Uses instructor library as LLM abstraction layer — not a direct OpenAI/Anthropic dependency.

Warnings

breaking v2.0 renamed all core classes: BaseAgent → AtomicAgent, BaseAgentConfig → AgentConfig, AgentMemory → ChatHistory, BaseAgentInputSchema → BasicChatInputSchema, BaseAgentOutputSchema → BasicChatOutputSchema. All v1 imports raise ImportError.
Fix: See full rename mapping at github.com/BrainBlend-AI/atomic-agents/blob/main/UPGRADE_DOC.md
breaking All .lib import paths removed in v2. 'from atomic_agents.lib.base.base_io_schema import BaseIOSchema' → 'from atomic_agents import BaseIOSchema'. 'from atomic_agents.lib.components.*' → 'from atomic_agents.context.*'.
Fix: atomic_agents.lib.base.* → atomic_agents.*; atomic_agents.lib.components.* → atomic_agents.context.*; atomic_agents.lib.factories.* → atomic_agents.connectors.mcp.*
breaking run_async() behavior changed in v2. Previously a streaming generator, now returns a complete response. Use run_async_stream() for streaming.
Fix: Replace async for chunk in agent.run_async() with response = await agent.run_async() or use run_async_stream() for streaming.
breaking BaseTool now uses generic type parameters in v2. Custom tools from v1 break — must add type parameters.
Fix: See tool migration in UPGRADE_DOC.md for generic type parameter syntax.
gotcha atomic-agents requires instructor as its LLM client wrapper. Raw OpenAI/Anthropic clients do not work — must be wrapped with instructor.from_openai() or equivalent.
Fix: client = instructor.from_openai(OpenAI()) then pass to AgentConfig(client=client, ...)
gotcha LLMs trained pre-2025 will generate v1 patterns (BaseAgent, .lib imports). These all break on v2.
Fix: All BaseAgent → AtomicAgent. All atomic_agents.lib.* paths need updating per rename table.

Install

pip install atomic-agents Python
pip install atomic-agents openai instructor Python (with OpenAI)

Imports

AtomicAgent (v2 — current)

import instructor
from openai import OpenAI
from atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BasicChatOutputSchema
from atomic_agents.context import ChatHistory, SystemPromptGenerator

client = instructor.from_openai(OpenAI())
history = ChatHistory()

agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](
    config=AgentConfig(
        client=client,
        model='gpt-4o-mini',
        history=history
    )
)

response = agent.run(BasicChatInputSchema(chat_message='Hello!'))
print(response.chat_message)

v1 used BaseAgent, BaseAgentConfig, AgentMemory from deep .lib paths. v2 renamed to AtomicAgent, AgentConfig, ChatHistory and flattened imports. All v1 import paths break with ImportError.

run_async (v2 behavior change)

# v2: run_async returns complete response
response = await agent.run_async(BasicChatInputSchema(chat_message='Hello'))
print(response.chat_message)

# v2: use run_async_stream for streaming
async for partial in agent.run_async_stream(BasicChatInputSchema(chat_message='Hello')):
    print(partial)

Breaking behavior change: in v1 run_async() was a streaming generator. In v2 it returns a complete response. Use run_async_stream() for async streaming.

Quickstart

Minimal atomic-agents v2 agent with OpenAI.

# pip install atomic-agents openai instructor
import instructor
from openai import OpenAI
from atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BasicChatOutputSchema
from atomic_agents.context import ChatHistory

client = instructor.from_openai(OpenAI())

agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](
    config=AgentConfig(
        client=client,
        model='gpt-4o-mini',
        history=ChatHistory()
    )
)

response = agent.run(BasicChatInputSchema(chat_message='What is quantum computing?'))
print(response.chat_message)

view raw JSON →