Install & Compatibility
Where this runs
tested against v1.1.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.952s · 126.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 21.1s · import 1.973s · 128MB
206MB installed
● package 206MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AtomicAgent
✓ from atomic_agents import AtomicAgent
✗ from atomic_agents import AtomicAgent
ChatHistory
✓ from atomic_agents.context import ChatHistory
✗ from atomic_agents.context import ChatHistory
SystemPromptGenerator
✓ from atomic_agents.context import SystemPromptGenerator
✗ from atomic_agents.context import SystemPromptGenerator
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)
atomic-agents --version
Debug
Known issues
breakingv2.0 renamed all core classes: BaseAgent → AtomicAgent, BaseAgentConfig → AgentConfig, AgentMemory → ChatHistory, BaseAgentInputSchema → BasicChatInputSchema, BaseAgentOutputSchema → BasicChatOutputSchema. All v1 imports raise ImportError.fixSee full rename mapping at github.com/BrainBlend-AI/atomic-agents/blob/main/UPGRADE_DOC.md
affects: >= 2.0.0
breakingAll .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.*'.fixatomic_agents.lib.base.* → atomic_agents.*; atomic_agents.lib.components.* → atomic_agents.context.*; atomic_agents.lib.factories.* → atomic_agents.connectors.mcp.*
affects: >= 2.0.0
breakingrun_async() behavior changed in v2. Previously a streaming generator, now returns a complete response. Use run_async_stream() for streaming.fixReplace async for chunk in agent.run_async() with response = await agent.run_async() or use run_async_stream() for streaming.
affects: >= 2.0.0
breakingBaseTool now uses generic type parameters in v2. Custom tools from v1 break — must add type parameters.fixSee tool migration in UPGRADE_DOC.md for generic type parameter syntax.
affects: >= 2.0.0
gotchaatomic-agents requires instructor as its LLM client wrapper. Raw OpenAI/Anthropic clients do not work — must be wrapped with instructor.from_openai() or equivalent.fixclient = instructor.from_openai(OpenAI()) then pass to AgentConfig(client=client, ...)
affects: all
gotchaLLMs trained pre-2025 will generate v1 patterns (BaseAgent, .lib imports). These all break on v2.fixAll BaseAgent → AtomicAgent. All atomic_agents.lib.* paths need updating per rename table.
affects: all
breakingThe 'instructor' library, a core dependency of 'atomic-agents', utilizes Python 3.10+ type annotation syntax (e.g., `str | Path`). This causes a `TypeError: Unable to evaluate type annotation 'str | Path'` or `TypeError: unsupported operand type(s) for |: 'type' and 'type'` when `atomic-agents` is run on Python versions prior to 3.10.fixUpgrade the Python environment to version 3.10 or newer.
affects: atomic-agents >= 1.0.26 on Python < 3.10
gotchaThe `openai.OpenAI()` client, used by `instructor` within `atomic-agents`, requires an API key to be configured. This can be done by setting the `OPENAI_API_KEY` environment variable or by passing `api_key='your_key'` directly to the `OpenAI` client constructor.fixEnsure the `OPENAI_API_KEY` environment variable is set, or initialize the OpenAI client with `client = instructor.from_openai(OpenAI(api_key='YOUR_OPENAI_API_KEY'))`.
affects: all
Upgrade
Version history
2.10.2latest on PyPI · released Aug 24, 2026
Audit
Dependencies
instructorrequiredRequired LLM abstraction layer. atomic-agents wraps instructor clients.
pydanticrequiredRequired for BaseIOSchema and typed agent schemas.
openaioptionalRequired for OpenAI provider. Install separately.