# Onboarding

## What is an agent?

An agent is a loop that lets a language model choose actions. In a normal script, you write every step ahead of time. In an agent script, you give the model a goal, a set of tools, and rules for when to stop.

If you know Python functions, a tool is just a Python function plus a JSON schema. The schema tells the model when the function is available and what arguments it accepts. The Python function still runs in normal Python.

## What should you learn first?

Learn the repo in this order:

| Step | Read or run | Why |
|------|-------------|-----|
| 1 | `ch01_react_from_scratch/atlas_v01.py` | Shows the whole ReAct loop without framework abstraction |
| 2 | `shared/config.py` | Shows how keys and model defaults are loaded from `.env` |
| 3 | `shared/skills.py` | Shows how tools become reusable skill classes |
| 4 | `ch03_tools_and_skills/atlas_v03.py` | Shows how an agent registers and dispatches skills |
| 5 | `ch05_state_graphs/code_review_agent.py` | Shows stateful workflows, retry routing, and human gates |
| 6 | `ch15_agent_harness/harness.py` | Shows how to limit filesystem and shell access |
| 7 | `ch18_evaluation/eval_harness.py` | Shows how to test agent behavior beyond final text |
| 8 | `ch20_capstone/atlas_capstone.py` | Shows how the major patterns compose into a larger workflow |

## How does the first agent work?

The first agent has five parts:

| Part | File | What it does |
|------|------|--------------|
| Environment loading | `shared/config.py` | Loads `.env`, reads `OPENAI_API_KEY`, and exposes `OPENAI_MODEL` |
| Tool implementation | `ch01_react_from_scratch/atlas_v01.py` | Implements `search_web` and `read_url` |
| Tool schema | `ch01_react_from_scratch/atlas_v01.py` | Describes those functions to the OpenAI API |
| Agent loop | `run_atlas()` | Calls the model, executes requested tools, appends tool results, and repeats |
| CLI wrapper | `if __name__ == "__main__"` | Reads the user question from command-line arguments |

That structure repeats throughout the repo. Later chapters swap the tool source, model provider, control loop, or runtime environment, but the basic contract stays the same: the model requests an action, Python validates and performs it, then the result goes back into the model context.

## Why are there so many chapter folders?

The repo teaches patterns separately so you can see each moving part before combining them. Chapter 1 starts with a raw web research agent. Chapter 3 introduces reusable skills. Chapter 4 routes between specialist agents. Chapter 5 introduces LangGraph state. Chapter 14 adds guardrails. Chapter 15 adds a harness. Chapter 18 evaluates trajectories. Chapter 20 combines the patterns into an engineering assistant.

## What should a future user do?

Use the root chapter examples first. They are usually the main book examples and are easier to run than `online/` supplements.

When a chapter has `online/`, treat it as optional expansion material. Those files often need additional packages, external services, or provider-specific setup.

## What should a future developer do?

Make changes in the smallest layer that matches the goal:

| Goal | Best starting point |
|------|---------------------|
| Add or change a provider key or model default | `shared/config.py` |
| Add a reusable tool | `shared/skills.py` |
| Add a declarative skill | `shared/declarative_skills/` or `ch09_agent_skills/skills/` |
| Add a stateful workflow | Chapter 5 patterns, then `ch20_capstone/atlas_capstone.py` |
| Add safety checks | Chapter 14 guardrails or chapter 15 harness patterns |
| Add evaluation coverage | `ch18_evaluation/eval_harness.py` or `ch18_evaluation/online/ci_eval_runner.py` |
| Deploy an API surface | `ch19_deployment/api.py` |

## Why does the repo use both code skills and Markdown skills?

Code skills execute behavior. Markdown skills describe behavior.

`shared/skills.py` contains executable skills such as `WebSkill`, `FileSkill`, and `CodeSkill`. `shared/declarative_skills/` and `ch09_agent_skills/skills/` contain instructions that can be loaded into a model prompt so the model follows a process.

Both are useful. Executable skills give the agent capabilities. Declarative skills give the agent procedure and judgment.

## Where to go next

After the quickstart, read [agent patterns by chapter](../concepts/agent-patterns-by-chapter.md). When you are ready to modify code, read [system design](../architecture/system-design.md) and [skills, tools, and safety](../concepts/skills-tools-and-safety.md).