# Atlas Agents

Atlas Agents is a Python learning codebase for building AI agents from first principles through production-oriented patterns. It is for readers who know Python and want a fast path into ReAct loops, tools, skills, state graphs, guardrails, evaluation, deployment, and autonomous engineering workflows.

This tutorial edition is based on [agulli/atlas-agents](https://github.com/agulli/atlas-agents). It adds extensive tutorial documentation and an interactive HTML course hub.

---

## Documentation

| Section | What's inside |
|---------|---------------|
| [Interactive course hub](course/index.html) | Dynamic learning path with progress tracking, module filters, labs, and knowledge checks |
| [Live course hub](https://az9713.github.io/atlas-agent-tutorial/docs/course/) | GitHub Pages version of the HTML learning hub |
| [What this is](overview/what-is-this.md) | Mental model, repository shape, and project boundaries |
| [Key concepts](overview/key-concepts.md) | Plain-language definitions for agent development terms used here |
| [Prerequisites](getting-started/prerequisites.md) | Python, API keys, optional services, and dependency expectations |
| [Quickstart](getting-started/quickstart.md) | Fastest path to run the first working example |
| [Onboarding](getting-started/onboarding.md) | Beginner-friendly learning path through the chapters |
| [Agent patterns by chapter](concepts/agent-patterns-by-chapter.md) | How the repo evolves from simple agents to the capstone |
| [Skills, tools, and safety](concepts/skills-tools-and-safety.md) | How tool schemas, skill registries, harnesses, and guardrails fit together |
| [System design](architecture/system-design.md) | Developer-oriented architecture and control flow |
| [Chapter and command reference](reference/chapter-and-command-reference.md) | Runnable examples, CLI flags, endpoints, config, and known setup gaps |
| [Common issues](troubleshooting/common-issues.md) | Syntax errors, missing dependencies, API keys, Docker gaps, and path issues |

## Recommended reading order

| Order | Read | Why |
|-------|------|-----|
| 1 | [Interactive course hub](course/index.html) | Guides the whole journey with progress, modules, labs, and checks |
| 2 | [Onboarding](getting-started/onboarding.md) | Builds the beginner mental model before running code |
| 3 | [Quickstart](getting-started/quickstart.md) | Runs the first working examples |
| 4 | [Key concepts](overview/key-concepts.md) | Defines the terms used across chapters |
| 5 | [Agent patterns by chapter](concepts/agent-patterns-by-chapter.md) | Explains the learning arc from chapter 1 to the capstone |
| 6 | [Skills, tools, and safety](concepts/skills-tools-and-safety.md) | Explains the main extension and safety points |
| 7 | [System design](architecture/system-design.md) | Gives developers the architecture and control-flow view |
| 8 | [Chapter and command reference](reference/chapter-and-command-reference.md) | Provides commands, endpoints, flags, and setup specifics |
| 9 | [Common issues](troubleshooting/common-issues.md) | Helps debug setup and optional examples |

For a true beginner, start with the [interactive course hub](course/index.html), read [onboarding](getting-started/onboarding.md), run [quickstart](getting-started/quickstart.md), inspect `ch01_react_from_scratch/atlas_v01.py`, then continue with [agent patterns by chapter](concepts/agent-patterns-by-chapter.md).