{"id":151,"library":"atomic-agents","title":"Atomic Agents","description":"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.","status":"active","version":"2.7.4","language":"python","source_language":"en","source_url":"https://github.com/BrainBlend-AI/atomic-agents","tags":["atomic-agents","agents","instructor","pydantic","python","llm","typed"],"install":[{"cmd":"pip install atomic-agents","lang":"bash","label":"Python"},{"cmd":"pip install atomic-agents openai instructor","lang":"bash","label":"Python (with OpenAI)"}],"dependencies":[{"reason":"Required LLM abstraction layer. atomic-agents wraps instructor clients.","package":"instructor","optional":false},{"reason":"Required for BaseIOSchema and typed agent schemas.","package":"pydantic","optional":false},{"reason":"Required for OpenAI provider. Install separately.","package":"openai","optional":true}],"imports":[{"note":"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.","wrong":"from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig\nfrom atomic_agents.lib.components.agent_memory import AgentMemory\n\nagent = BaseAgent(\n    BaseAgentConfig(client=client, model='gpt-4o-mini', memory=AgentMemory())\n)","symbol":"AtomicAgent (v2 — current)","correct":"import instructor\nfrom openai import OpenAI\nfrom atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BasicChatOutputSchema\nfrom atomic_agents.context import ChatHistory, SystemPromptGenerator\n\nclient = instructor.from_openai(OpenAI())\nhistory = ChatHistory()\n\nagent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](\n    config=AgentConfig(\n        client=client,\n        model='gpt-4o-mini',\n        history=history\n    )\n)\n\nresponse = agent.run(BasicChatInputSchema(chat_message='Hello!'))\nprint(response.chat_message)"},{"note":"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.","wrong":"# v1: run_async was a streaming generator\nasync for chunk in agent.run_async(input_schema):\n    print(chunk)","symbol":"run_async (v2 behavior change)","correct":"# v2: run_async returns complete response\nresponse = await agent.run_async(BasicChatInputSchema(chat_message='Hello'))\nprint(response.chat_message)\n\n# v2: use run_async_stream for streaming\nasync for partial in agent.run_async_stream(BasicChatInputSchema(chat_message='Hello')):\n    print(partial)"}],"quickstart":{"code":"# pip install atomic-agents openai instructor\nimport instructor\nfrom openai import OpenAI\nfrom atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BasicChatOutputSchema\nfrom atomic_agents.context import ChatHistory\n\nclient = instructor.from_openai(OpenAI())\n\nagent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](\n    config=AgentConfig(\n        client=client,\n        model='gpt-4o-mini',\n        history=ChatHistory()\n    )\n)\n\nresponse = agent.run(BasicChatInputSchema(chat_message='What is quantum computing?'))\nprint(response.chat_message)","lang":"python","description":"Minimal atomic-agents v2 agent with OpenAI."},"warnings":[{"fix":"See full rename mapping at github.com/BrainBlend-AI/atomic-agents/blob/main/UPGRADE_DOC.md","message":"v2.0 renamed all core classes: BaseAgent → AtomicAgent, BaseAgentConfig → AgentConfig, AgentMemory → ChatHistory, BaseAgentInputSchema → BasicChatInputSchema, BaseAgentOutputSchema → BasicChatOutputSchema. All v1 imports raise ImportError.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"atomic_agents.lib.base.* → atomic_agents.*; atomic_agents.lib.components.* → atomic_agents.context.*; atomic_agents.lib.factories.* → atomic_agents.connectors.mcp.*","message":"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.*'.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"Replace async for chunk in agent.run_async() with response = await agent.run_async() or use run_async_stream() for streaming.","message":"run_async() behavior changed in v2. Previously a streaming generator, now returns a complete response. Use run_async_stream() for streaming.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"See tool migration in UPGRADE_DOC.md for generic type parameter syntax.","message":"BaseTool now uses generic type parameters in v2. Custom tools from v1 break — must add type parameters.","severity":"breaking","affected_versions":">= 2.0.0"},{"fix":"client = instructor.from_openai(OpenAI()) then pass to AgentConfig(client=client, ...)","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"All BaseAgent → AtomicAgent. All atomic_agents.lib.* paths need updating per rename table.","message":"LLMs trained pre-2025 will generate v1 patterns (BaseAgent, .lib imports). These all break on v2.","severity":"gotcha","affected_versions":"all"},{"fix":"Upgrade the Python environment to version 3.10 or newer.","message":"The '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.","severity":"breaking","affected_versions":"atomic-agents >= 1.0.26 on Python < 3.10"},{"fix":"Ensure 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'))`.","message":"The `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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T08:58:36.606Z","next_check":"2026-06-24T00:00:00.000Z","problems":[{"fix":"Update imports to remove '.lib', e.g., 'from atomic_agents import Agent'.","cause":"In version 2.0, the '.lib' subpackage was removed from import paths.","error":"ModuleNotFoundError: No module named 'atomic_agents.lib'"},{"fix":"Refer to the latest documentation to find the new class name and update the import accordingly.","cause":"In version 2.0, class names were changed; 'Agent' was likely renamed.","error":"ImportError: cannot import name 'Agent' from 'atomic_agents'"},{"fix":"Specify input and output schemas when instantiating, e.g., 'AtomicAgent[InputSchema, OutputSchema]'.","cause":"In version 2.0, generic type parameters were added, requiring explicit type annotations.","error":"TypeError: 'AtomicAgent' object is not subscriptable"},{"fix":"Create an 'AtomicAgent' instance and call 'run' on it, e.g., 'agent = AtomicAgent(); agent.run(input)'.","cause":"The 'run' method is now an instance method of 'AtomicAgent' and not a module-level function.","error":"AttributeError: module 'atomic_agents' has no attribute 'run'"},{"fix":"Ensure that the 'chat_message' field is provided when creating an input schema instance.","cause":"The 'chat_message' field is mandatory in the 'BasicChatInputSchema'.","error":"ValueError: Missing required field 'chat_message' in input schema"}],"ecosystem":"pypi","meta_description":null,"install_score":85,"install_tag":"verified","quickstart_score":20,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.11,"mem_mb":36.8,"disk_size":"116.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.04,"mem_mb":36.8,"disk_size":"116.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.33,"mem_mb":36.8,"disk_size":"118M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.31,"mem_mb":36.8,"disk_size":"118M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.83,"mem_mb":39.6,"disk_size":"127.2M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.81,"mem_mb":39.6,"disk_size":"127.2M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.27,"mem_mb":39.6,"disk_size":"129M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.29,"mem_mb":39.6,"disk_size":"129M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.75,"mem_mb":38.5,"disk_size":"258.7M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.75,"mem_mb":38.5,"disk_size":"258.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.75,"mem_mb":38.5,"disk_size":"242M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.74,"mem_mb":38.5,"disk_size":"242M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.5,"mem_mb":40.1,"disk_size":"258.5M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.41,"mem_mb":40.1,"disk_size":"258.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.51,"mem_mb":40.1,"disk_size":"242M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.48,"mem_mb":40.1,"disk_size":"242M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}