Atomic Agents: a Pydantic-first framework for pipelines you can predict

The problem Atomic Agents solves: agents that behave like software

Most agent frameworks optimize for autonomy. You describe a goal, the framework decides which tools to call and in what order, and the control flow lives inside the model's reasoning. That is fine for demos and awkward for systems that have to produce the same shape of output on every run.

Atomic Agents takes the opposite position. The README frames the project around atomicity: every component is single-purpose, reusable, composable and predictable. An agent is not a black box that decides things; it is a typed object with a declared input schema and a declared output schema. The framework's own description of the audience is developers who want to build agentic pipelines without giving up developer experience and maintainability.

That framing matters because it changes what you write. Instead of prompt strings that you tune until the output stops breaking, you write a Pydantic model that describes the output, and the model is the contract. If the LLM returns something that does not fit the schema, that is a validation failure you can see, not a silent drift. The README is explicit that the framework is built on Instructor and Pydantic, so the validation layer is not an add-on bolted onto the side; it is the mechanism the whole design rests on.

How an agent is assembled: schemas, system prompts and history

The anatomy described in the README has four moving parts. An AtomicAgent is generic over two schemas, one for input and one for output. An AgentConfig carries the client, the model name, a SystemPromptGenerator and a ChatHistory. The SystemPromptGenerator takes three lists, background, steps and output_instructions, and turns them into the system prompt. The history object holds the conversation.

The data flow is straightforward. You construct an input schema instance, pass it to agent.run(), and get back an instance of the output schema. Because both ends are Pydantic models, the intermediate representation is structured rather than free text. The README's chaining section points at the consequence: schemas can be chained, so the output schema of one agent can be the input schema of the next. That is the composition story. Pipelines are built by wiring typed agents together rather than by asking one agent to orchestrate everything.

Context providers are the third component type. The README lists agents, tools and context providers as the reusable atoms, and the CLI can download tools. Context providers are how external state gets into a run without being hardcoded into the system prompt, which keeps the prompt generator itself a small, inspectable object.

One design consequence is worth naming. Because the system prompt is generated from lists rather than written as one string, you get some structure for free, but you also give up fine-grained control over prompt layout. If your use case depends on a carefully crafted prompt with unusual formatting, the generator's three-list shape may feel like a constraint.

Installing Atomic Agents and running a first agent

Install the package from PyPI. Python 3.12 or newer is required, per pyproject.toml.

pip install atomic-agents

OpenAI support is included by default. For other providers, the README instructs you to install the matching Instructor extra.

pip install instructor[groq]         # for Groq
pip install instructor[anthropic]    # for Anthropic
pip install instructor[google-genai] # for Gemini

This installation also puts the Atomic Assembler CLI on your path. The console script is registered in pyproject.toml as atomic, pointing at atomic_assembler.main:main, so you invoke it as atomic. The README says the CLI can download Tools, with Agents and Pipelines described as coming later.

For a first run, the README's quick example defines a custom output schema with two fields, a chat message and a list of suggested follow-up questions, then builds an agent from that schema.

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

class CustomOutputSchema(BaseIOSchema):
    chat_message: str = Field(..., description="The chat message from the agent.")
    suggested_questions: list[str] = Field(..., description="Suggested follow-up questions.")

client = instructor.from_openai(OpenAI())

The rest of the example constructs a SystemPromptGenerator with background, steps and output_instructions lists, then instantiates AtomicAgent[BasicChatInputSchema, CustomOutputSchema] with an AgentConfig holding the client, the model name, the prompt generator and a ChatHistory. Calling agent.run(BasicChatInputSchema(chat_message=...)) returns an object whose chat_message and suggested_questions attributes you can print. The thing to watch on the first run is that the printed output is an attribute access on a validated object, not a parsed string. If the model returns a malformed list, you get an exception at that boundary instead of a wrong value downstream.

The README also mentions AI-assisted development support: project instructions for Cursor, Windsurf, Cline, Continue and Aider, agent skills for Claude Code, Cursor, Copilot, Codex, Windsurf and Gemini CLI, and docs for LLMs. Those files exist in the repository root as AGENTS.md and context7.json, though the README does not spell out what each one contains.

Where Atomic Agents is the wrong tool

The framework's stated trade-off is control at the cost of autonomy. If your problem is genuinely open-ended, where the right sequence of tool calls is unknown until runtime, you will spend your time pre-declaring schemas for steps you cannot yet name. The README's own contrast is with frameworks that focus on autonomous multi-agent systems, and it argues those often lack the control and predictability real applications need. Read that in reverse: if you want the framework to discover the plan, this is not the framework.

Version compatibility is a second hard boundary. pyproject.toml sets requires-python to ">=3.12", and the classifiers list only Python 3.12 and 3.13. There is no path for a 3.11 codebase short of upgrading the interpreter. The package is also classified as Development Status 4 - Beta, so the API surface is not presented as frozen.

The v2.0 release notes in the README describe a breaking change from v1.x, and the repository carries a separate UPGRADE_DOC.md. If you are on v1.x, the upgrade is not a version bump you can do casually on a Friday afternoon. The README links to that document rather than summarizing it, so the details live there.

Finally, the CLI is described as downloading Tools, with Agents and Pipelines noted as coming soon. If your adoption plan depends on the CLI generating whole pipelines, that capability is not there yet according to the README.

Atomic Agents compared with LangChain and Pydantic AI

The most useful comparison is with Pydantic AI, because both projects put Pydantic at the center. Pydantic AI is built around a typed agent abstraction with dependency injection and a result type, and it aims to feel like a normal Python web framework for LLM calls. Atomic Agents is organized around composition of three component kinds, agents, tools and context providers, with the system prompt assembled from lists and history as an explicit object you pass in. The practical difference shows up in how you build a pipeline: Pydantic AI's model is one agent with typed dependencies, while Atomic Agents' model is several agents chained by matching output schemas to input schemas. If your work is naturally a sequence of transformations, the second shape reads more directly.

Against LangChain, the difference is scope. LangChain ships a large surface of integrations, retrievers, memory types and orchestration primitives. Atomic Agents deliberately stays small: the runtime dependencies in pyproject.toml are Instructor, Pydantic, Rich, GitPython, Pyfiglet, Textual, PyYAML, Requests, the MCP CLI and LiteLLM. That is a short list, and it means fewer abstractions between your code and the model call. The cost is that anything LangChain provides as a ready-made component, you write yourself.

CrewAI and AutoGen sit further away, since both lean into multi-agent conversation and role assignment. Atomic Agents does not model roles or debates. It models typed inputs and outputs. Choose based on whether your problem is a conversation between agents or a data pipeline that happens to call models.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-08-24. Releases v2.10.0, v2.10.1 and v2.10.2 landed on 2026-08-11, 2026-08-20 and 2026-08-24 respectively, so the project is moving in small increments rather than large jumps. The version in pyproject.toml, 2.10.2, matches the newest release tag.

For upgrade cost, the relevant artifacts are UPGRADE_DOC.md at the repository root and the v2.0 section of the README. The README documents that upgrading from v1.x involves breaking changes and points to that document. Pin your dependency accordingly: requirements.txt in the repository pins instructor to exactly 1.14.5 and pydantic to >=2.10.3,<3.0.0, while pyproject.toml pins instructor==1.14.5 and pydantic>=2.11.0,<3.0.0. Those two files disagree on the Pydantic lower bound, which is a small but real signal that the repository's own dependency declarations are not fully synchronized. If you depend on Atomic Agents, pin the version you tested rather than floating.

The licence is MIT, declared in both the LICENSE file and the pyproject.toml license field. MIT permits commercial use, modification and redistribution with the copyright notice and permission notice retained. That is a permissive arrangement, but it says nothing about the licences of the model providers you call or of Instructor and its extras, which you should check separately for your own distribution. This is not legal advice.

Editorial conclusion

Adopt Atomic Agents if you already think in Pydantic models and want each agent, tool and context provider to be a small, testable unit you can reorder without rewriting prompts. Skip it if you need the framework itself to plan multi-step autonomy, or if you are pinned below Python 3.12, since pyproject.toml sets requires-python to >=3.12. Before committing, verify the upgrade path in UPGRADE_DOC.md, because the README documents a breaking v1.x to v2.x migration, and check that your provider has an instructor extra listed in the Instructor docs, since only OpenAI ships by default.

Frequently asked questions

Official sources

1. Eigenwise/atomic-agents on GitHub
2. License: MIT
3. Project website
4. README
5. Releases