/framework

name: framework
description: Guide for the Atomic Agents Python framework — schemas, agents, tools, context providers, prompts, orchestration, and provider configuration. Use when code imports from `atomic_agents`, defines an `AtomicAgent`, `BaseTool`, or `BaseIOSchema`, or the user asks about multi-agent orchestration or LLM-provider wiring in an atomic-agents project.

Atomic Agents Framework

Atomic Agents is a lightweight Python framework for building LLM applications with typed, structured input and output. It layers on top of [Instructor](https://python.useinstructor.com) and Pydantic so every interaction between user, agent, tool, and context is a validated schema.

This skill orients Claude on the framework and routes to focused reference files as the task requires.

Core abstractions

| Concept | Class | Role | |---|---|---| | Schema | `BaseIOSchema` | Typed input/output contract — every agent/tool I/O is one | | Agent | `AtomicAgent[In, Out]` | LLM-backed transformer from input schema to output schema | | Config | `AgentConfig` | Wires client, model, history, prompt, roles, API params | | Prompt | `SystemPromptGenerator` | Three-section prompt: background, steps, output_instructions | | History | `ChatHistory` | Conversation state, serializable, token-counted | | Tool | `BaseTool[In, Out]` | Deterministic capability the agent can invoke | | Context | `BaseDynamicContextProvider` | Dynamic section injected into the system prompt at runtime |

All communication between these uses `BaseIOSchema` subclasses with **docstring-required** descriptions.

Canonical imports

from atomic_agents import (
    AtomicAgent, AgentConfig,
    BasicChatInputSchema, BasicChatOutputSchema,
    BaseIOSchema, BaseTool, BaseToolConfig,
)
from atomic_agents.context import (
    ChatHistory, Message,
    SystemPromptGenerator, BaseDynamicContextProvider,
)
# Optional: MCP interop
from atomic_agents.connectors.mcp import fetch_mcp_tools, MCPTransportType

Do not use legacy paths like `atomic_agents.lib.base.*` or `atomic_agents.agents.base_agent` — those were retired. Import from the top-level package where possible.

Minimum viable agent

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

client = instructor.from_openai(openai.OpenAI(api_key=os.environ["OPENAI_API_KEY"]))

agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](
    config=AgentConfig(
        client=client,
        model="gpt-5-mini",
        history=ChatHistory(),
    )
)

reply = agent.run(BasicChatInputSchema(chat_message="Hello"))
print(reply.chat_message)

`AtomicAgent` and `BaseTool` use PEP 695 generics — the type parameters carry runtime information, so write them explicitly and keep them accurate. Full runnable version: `atomic-examples/quickstart/quickstart/1_0_basic_chatbot.py`.

Targeted creation skills

For the four most common authoring tasks, dedicated atomic skills give a step-by-step workflow (clarify → write → verify → hand off) instead of just reference material. Prefer them when the user is actively building something specific.

| User intent | Atomic skill | |---|---| | "create a schema" / "design the input/output schema" | `atomic-agents:create-atomic-schema` | | "create an agent" / "add another agent" / "wire up an `AtomicAgent`" | `atomic-agents:create-atomic-agent` | | "add a tool" / "wrap an API as a tool" / "build a `BaseTool`" | `atomic-agents:create-atomic-tool` | | "add a context provider" / "inject X into the prompt" / "wire up RAG" | `atomic-agents:create-atomic-context-provider` | | "my agent is broken / crashing / returning garbage" + a traceback or error | `atomic-agents:troubleshoot` |

These skills auto-trigger on the matching phrasing. The reference files below are what they (and you) load for deeper material.

Decision routing

Pick the reference file that matches the task. Each is loaded only when read.

| Task | Reference | |---|---| | Design or validate an input/output schema | [references/schemas.md](references/schemas.md) | | Build, configure, or run an agent | [references/agents.md](references/agents.md) | | Write a tool the agent will invoke | [references/tools.md](references/tools.md) | | Inject dynamic data into the system prompt | [references/context-providers.md](references/context-providers.md) | | Structure the system prompt | [references/prompts.md](references/prompts.md) | | Coordinate multiple agents | [references/orchestration.md](references/orchestration.md) | | Manage conversation state and multi-agent memory | [references/memory.md](references/memory.md) | | Register telemetry, retries, or logging | [references/hooks.md](references/hooks.md) | | Swap LLM provider or configure roles | [references/providers.md](references/providers.md) | | Decide the project layout or `pyproject.toml` | [references/project-structure.md](references/project-structure.md) | | Write tests for agents and tools | [references/testing.md](references/testing.md) |

When a concept is unclear, start from the user's verb: *create a schema* → `create-atomic-schema` skill, *hook up a weather API* → `create-atomic-tool` skill, *inject user name into prompt* → `create-atomic-context-provider` skill, *route between agents* → orchestration reference.

Working style

Follow these defaults unless the project says otherwise. The reference files go deeper on each.

**Schemas are the contract.** Design the `BaseIOSchema` pair before writing the agent. Field descriptions flow into the LLM prompt via Instructor, so write them for the model, not just the developer. Every subclass needs a non-empty docstring — the framework enforces this at class-definition time.

**System prompts have three sections.** Use `SystemPromptGenerator(background=..., steps=..., output_instructions=...)`. Put persona in `background`, the ordered procedure in `st