# agulli/atlas-agents architecture

> Architecture diagram of the GitHub repository agulli/atlas-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agulli/atlas-agents
- Repository: https://github.com/agulli/atlas-agents

## Overview

This repository is a **chapter-by-chapter reference implementation** for the book, not a single monolithic application. Architecturally, it is a collection of **independent agent demos** that all share a small common foundation and then branch into specialized patterns: prompting, tools, handoffs, graph workflows, multi-agent orchestration, model routing, protocol integrations, and memory.

1. **Top-level structure**
   - Each `chXX_*` directory is a self-contained subsystem for one architectural pattern.
   - Most chapters contain a core Python example plus an `online/` subfolder for variants that depend on external APIs, services, or richer runtime behavior.
   - The repo is designed as a learning surface: each folder isolates one agent architecture so it can be diagrammed independently.

2. **Shared foundation**
   - `shared/config.py` and `shared/skills.py` act as the common support layer.
   - `shared/declarative_skills/` contains many reusable skill definitions as Markdown assets, suggesting a prompt/skill registry pattern rather than hardcoded behavior only.
   - `requirements.txt` and `.env.example` define the runtime envelope: Python dependencies plus environment-based secrets/configuration for model providers and integrations.

3. **Chapter 1: baseline agent loop**
   - `ch01_react_from_scratch/atlas_v01.py` is the minimal ReAct-style agent core.
   - The `online/` variants extend that baseline into provider-specific and execution-mode variants such as Anthropic usage, plan-and-execute, and streaming.
   - This chapter establishes the smallest “agent kernel” used conceptually by later chapters.

4. **Chapter 2: prompt architecture layer**
   - This chapter focuses on prompt-shaping as a subsystem: chain-of-density prompting, multi-persona routing, prompt injection detection, and A/B testing.
   - The architectural boundary here is between **prompt construction/selection** and the downstream model call.
   - It emphasizes prompt governance rather than tool use or orchestration.

5. **Chapter 3: tools and skills**
   - `atlas_v03.py` and the `online/` examples show the transition from pure prompting to **capability-backed agents**.
   - The main theme is tool invocation and skill discovery, including API skills, database skills, and automatic skill discovery.
   - This introduces a clean separation between the agent and operational tools/data sources.

6. **Chapter 4: handoff and routing**
   - `triage.py` and the `online/` modules implement a support-style routing layer.
   - The architecture here is a **dispatcher + specialist agents** model: dynamic routing, escalation chains, and context-preserving handoff.
   - This is the first clear multi-agent boundary where one agent decides which other agent should continue.

7. **Chapter 5: state graphs and human-in-the-loop**
   - `code_review_agent.py` and the online graph examples point to a **stateful workflow engine** approach, aligned with LangGraph-style orchestration.
   - Important subpatterns include approval gates, parallel fan-out, and time-travel/debugging behavior.
   - The key boundary is no longer “one call per task,” but a persisted state machine with checkpoints and intervention points.

8. **Chapter 6: multi-agent crews**
   - These examples use a role-based crew architecture: newsletter production, memory-enabled crews, debate-with-jury, and hierarchical crews.
   - The structure is a collection of cooperating agents with explicit roles, rather than a single router or graph.
   - This chapter’s diagrams should show a team topology: coordinator, specialists, and sometimes evaluator/jury roles.

9. **Chapter 7: model portability**
   - This chapter abstracts over model providers and runtimes with benchmark, router, DSPy pipeline, and Ollama tool-calling examples.
   - The architectural concern is **model selection and portability**, not agent logic itself.
   - It implies an adapter layer that can switch between hosted APIs and local inference.

10. **Chapter 8: MCP and A2A integration**
   - `mcp_knowledge_server.py`, `mcp_github_server.py`, and the `online/` files illustrate protocol-driven connectivity.
   - MCP servers expose tools/data; A2A files demonstrate agent discovery and UI rendering for agent interactions.
   - This chapter is the integration boundary between agents and external tool/data ecosystems, including GitHub and client discovery flows.

11. **Chapter 9: declarative skill library**
   - `ch09_agent_skills/skills/*/SKILL.md` is a large catalog of reusable expert prompts/capabilities.
   - The architecture is declarative: each skill is packaged as a standalone artifact with a clear domain and expected behavior.
   - This supports composition by loading skills rather than embedding large instructions inside code.

12. **Chapter 10: Claude Code / autonomous coding workflow**
   - The `.claude/` configuration, `AGENTS.md`, and `online/` utilities suggest an agentic development pipeline around code validation and benchmarking.
   - The main concerns are autonomy, specification validation, and CI-style execution feedback.
   - This is a tooling-heavy subsystem oriented around software engineering workflows rather than user-facing product behavior.

13. **Chapter 11: memory systems**
   - `memory_agent.py` and the online variants cover memory decay, adaptive chunking, and graph-based retrieval with Neo4j.
   - The architecture splits into short-term/managed memory behavior and external persistent knowledge representation.
   - `graph_rag_neo4j.py` is the clearest boundary where agent reasoning meets graph-backed retrieval.

14. **External dependencies and runtime boundaries**
   - The repo is Python-centric, with online examples likely requiring API keys for model providers and possibly services like Neo4j or GitHub.
   - The chapters imply multiple external service boundaries: LLM APIs, local model runtime via Ollama, graph databases, MCP servers, and CI/automation hooks.
   - For an architecture diagram, the most important distinction is between **local orchestration code** in the repo and **external model/data/tool services**.

15. **How to read the repository as a system**
   - Think of it as a layered reference stack: baseline agent loop → prompt architecture → tools → handoffs → stateful graphs → multi-agent crews → model routing → protocol integration → reusable skills → coding automation → memory.
   - Each chapter is a distinct architectural pattern, but they all plug into the same broad agent ecosystem defined by shared config, skills, and environment variables.

Main entry points: [`ch03_tools_and_skills/atlas_v03.py`](https://github.com/agulli/atlas-agents/blob/main/ch03_tools_and_skills/atlas_v03.py) (Tools & skills), [`shared/config.py`](https://github.com/agulli/atlas-agents/blob/main/shared/config.py) (Config), [`ch07_model_portability/benchmark.py`](https://github.com/agulli/atlas-agents/blob/main/ch07_model_portability/benchmark.py) (Model router), [`ch01_react_from_scratch/atlas_v01.py`](https://github.com/agulli/atlas-agents/blob/main/ch01_react_from_scratch/atlas_v01.py) (Agent loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_foundation["Shared foundation"]
  node_shared_config["Config<br/>shared support<br/>[config.py]"]
  node_shared_skills["Skills helper<br/>shared support<br/>[skills.py]"]
  node_declarative_skills["Skill library<br/>skill registry"]
  node_runtime_env["Runtime envelope<br/>dependency/config<br/>[requirements.txt]"]
end

subgraph group_patterns["Core patterns"]
  node_ch01["Agent loop<br/>react kernel<br/>[atlas_v01.py]"]
  node_ch02["Prompt layer<br/>prompt governance"]
  node_ch03["Tools & skills<br/>tool-augmented agent<br/>[atlas_v03.py]"]
  node_ch04["Handoff router<br/>dispatcher<br/>[triage.py]"]
  node_ch05["State graphs<br/>workflow engine"]
  node_ch06["Crew system<br/>multi-agent team<br/>[newsletter_crew.py]"]
  node_ch07["Model router<br/>model portability<br/>[benchmark.py]"]
end

subgraph group_integrations["Integration layers"]
  node_ch08["Protocol bridge<br/>mcp/a2a integration"]
  node_ch09["Skill packs<br/>declarative skills"]
  node_ch10["Claude workflow<br/>autonomous coding<br/>[AGENTS.md]"]
  node_ch11[("Memory systems<br/>memory retrieval<br/>[memory_agent.py]")]
end

subgraph group_external["External systems"]
  node_llm_services(("Model APIs<br/>external service"))
  node_local_runtime(("Local runtime<br/>external service"))
  node_data_services(("Data services<br/>external service"))
  node_ci_hooks(("CI hooks<br/>external service"))
end

node_runtime_env -->|"configures"| node_shared_config
node_shared_config -->|"feeds"| node_ch01
node_shared_config -->|"feeds"| node_ch03
node_shared_config -->|"feeds"| node_ch07
node_shared_skills -->|"enables"| node_ch03
node_shared_skills -->|"enables"| node_ch06
node_declarative_skills -->|"powers"| node_ch09
node_declarative_skills -->|"powers"| node_ch10
node_ch01 -->|"evolves into"| node_ch02
node_ch02 -->|"extends into"| node_ch03
node_ch03 -->|"routes to"| node_ch04
node_ch04 -->|"formalizes into"| node_ch05
node_ch05 -->|"expands into"| node_ch06
node_ch06 -->|"abstracts over"| node_ch07
node_ch07 -->|"integrates with"| node_ch08
node_ch08 -->|"supports retrieval"| node_ch11
node_ch10 -->|"validates via"| node_ci_hooks
node_ch07 -->|"can use"| node_local_runtime
node_ch08 -->|"connects to"| node_data_services
node_ch11 -->|"stores in"| node_data_services
node_ch01 -->|"calls"| node_llm_services
node_ch02 -->|"calls"| node_llm_services
node_ch03 -->|"uses"| node_data_services

click node_shared_config "https://github.com/agulli/atlas-agents/blob/main/shared/config.py"
click node_shared_skills "https://github.com/agulli/atlas-agents/blob/main/shared/skills.py"
click node_declarative_skills "https://github.com/agulli/atlas-agents/tree/main/shared/declarative_skills"
click node_runtime_env "https://github.com/agulli/atlas-agents/blob/main/requirements.txt"
click node_ch01 "https://github.com/agulli/atlas-agents/blob/main/ch01_react_from_scratch/atlas_v01.py"
click node_ch02 "https://github.com/agulli/atlas-agents/tree/main/ch02_prompt_architecture"
click node_ch03 "https://github.com/agulli/atlas-agents/blob/main/ch03_tools_and_skills/atlas_v03.py"
click node_ch04 "https://github.com/agulli/atlas-agents/blob/main/ch04_handoffs/triage.py"
click node_ch05 "https://github.com/agulli/atlas-agents/blob/main/ch05_state_graphs/code_review_agent.py"
click node_ch06 "https://github.com/agulli/atlas-agents/blob/main/ch06_multi_agent/newsletter_crew.py"
click node_ch07 "https://github.com/agulli/atlas-agents/blob/main/ch07_model_portability/benchmark.py"
click node_ch08 "https://github.com/agulli/atlas-agents/blob/main/ch08_mcp_a2a/mcp_knowledge_server.py"
click node_ch09 "https://github.com/agulli/atlas-agents/tree/main/ch09_agent_skills/skills"
click node_ch10 "https://github.com/agulli/atlas-agents/blob/main/ch10_claude_code_antigravity/AGENTS.md"
click node_ch11 "https://github.com/agulli/atlas-agents/blob/main/ch11_memory/memory_agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shared_config,node_shared_skills,node_declarative_skills,node_runtime_env toneBlue
class node_ch01,node_ch02,node_ch03,node_ch04,node_ch05,node_ch06,node_ch07 toneAmber
class node_ch08,node_ch09,node_ch10,node_ch11 toneMint
class node_llm_services,node_local_runtime,node_data_services,node_ci_hooks toneRose
```

## Components

### Shared foundation

Common config, runtime envelope, and reusable skill assets used across chapters.

- [Config](https://github.com/agulli/atlas-agents/blob/main/shared/config.py): shared support · Environment and provider configuration shared by the examples. · `shared/config.py`
- [Skills helper](https://github.com/agulli/atlas-agents/blob/main/shared/skills.py): shared support · Common code for loading and using shared skills. · `shared/skills.py`
- [Skill library](https://github.com/agulli/atlas-agents/tree/main/shared/declarative_skills): skill registry · Reusable Markdown skill definitions used as declarative capability assets. · `shared/declarative_skills`
- [Runtime envelope](https://github.com/agulli/atlas-agents/blob/main/requirements.txt): dependency/config · Repository-wide Python dependencies and environment variable template. · `requirements.txt`

### Core patterns

Chapter 1 to 7 cover the main agent architecture patterns.

- [Agent loop](https://github.com/agulli/atlas-agents/blob/main/ch01_react_from_scratch/atlas_v01.py): react kernel · Minimal ReAct-style agent baseline and its online variants. · `ch01_react_from_scratch/atlas_v01.py`
- [Prompt layer](https://github.com/agulli/atlas-agents/tree/main/ch02_prompt_architecture): prompt governance · Prompt shaping, routing, injection defense, and A/B testing. · `ch02_prompt_architecture`
- [Tools & skills](https://github.com/agulli/atlas-agents/blob/main/ch03_tools_and_skills/atlas_v03.py): tool-augmented agent · Tool invocation, skill discovery, API skills, and database skills. · `ch03_tools_and_skills/atlas_v03.py`
- [Handoff router](https://github.com/agulli/atlas-agents/blob/main/ch04_handoffs/triage.py): dispatcher · Triage, escalation chains, and context-preserving routing between specialists. · `ch04_handoffs/triage.py`
- [State graphs](https://github.com/agulli/atlas-agents/blob/main/ch05_state_graphs/code_review_agent.py): workflow engine · Persisted agent workflows with approval gates, fan-out, and debugging. · `ch05_state_graphs/code_review_agent.py`
- [Crew system](https://github.com/agulli/atlas-agents/blob/main/ch06_multi_agent/newsletter_crew.py): multi-agent team · Role-based crews with coordinators, specialists, memory, and jury roles. · `ch06_multi_agent/newsletter_crew.py`
- [Model router](https://github.com/agulli/atlas-agents/blob/main/ch07_model_portability/benchmark.py): model portability · Benchmarking, routing, and local-vs-hosted model portability. · `ch07_model_portability/benchmark.py`

### Integration layers

Protocol, declarative skill, coding workflow, and memory subsystems.

- [Protocol bridge](https://github.com/agulli/atlas-agents/blob/main/ch08_mcp_a2a/mcp_knowledge_server.py): mcp/a2a integration · MCP servers and A2A discovery/rendering integrations. · `ch08_mcp_a2a/mcp_knowledge_server.py`
- [Skill packs](https://github.com/agulli/atlas-agents/tree/main/ch09_agent_skills/skills): declarative skills · Large catalog of standalone SKILL.md capability definitions. · `ch09_agent_skills/skills`
- [Claude workflow](https://github.com/agulli/atlas-agents/blob/main/ch10_claude_code_antigravity/AGENTS.md): autonomous coding · Claude Code-oriented validation, benchmarking, and CI-style automation. · `ch10_claude_code_antigravity/AGENTS.md`
- [Memory systems](https://github.com/agulli/atlas-agents/blob/main/ch11_memory/memory_agent.py): memory retrieval · Decay, chunking, and graph-backed long-term memory patterns. · `ch11_memory/memory_agent.py`

### External systems

Outside services and runtimes referenced by the online examples.

- **Model APIs**: external service · Hosted LLM providers used by the online examples.
- **Local runtime**: external service · Local inference/runtime such as Ollama used by portability examples.
- **Data services**: external service · GitHub, Neo4j, and other service integrations referenced by online modules.
- **CI hooks**: external service · Validation and execution feedback surfaces for autonomous coding workflows.

## Connections

- Runtime envelope → Config: configures · Environment values and dependencies feed shared configuration.
- Config → Agent loop: feeds · Common model and secret handling is reused by the baseline agent.
- Config → Tools & skills: feeds · Tool-augmented examples depend on the shared runtime configuration.
- Config → Model router: feeds · Model routing and benchmarking use shared provider settings.
- Skills helper → Tools & skills: enables · Shared skills support capability-backed agents.
- Skills helper → Crew system: enables · Crew examples can reuse common skills.
- Skill library → Skill packs: powers · The declarative skill catalog is the main chapter 9 asset.
- Skill library → Claude workflow: powers · Autonomous coding workflows can load reusable skill prompts.
- Agent loop → Prompt layer: evolves into · Prompt architecture refines the baseline agent loop.
- Prompt layer → Tools & skills: extends into · Prompt governance gives way to tool-backed capability use.
- Tools & skills → Handoff router: routes to · Tool use is complemented by specialist handoff routing.
- Handoff router → State graphs: formalizes into · Routing and escalation become a persisted workflow graph.
- State graphs → Crew system: expands into · Graph workflows broaden into multi-agent team topologies.
- Crew system → Model router: abstracts over · Crew orchestration sits above model portability concerns.
- Model router → Protocol bridge: integrates with · Portable model execution connects to protocol-based tool ecosystems.
- Protocol bridge → Memory systems: supports retrieval · Protocol integrations and external data sources feed memory systems.
- Claude workflow → CI hooks: validates via · Autonomous coding workflows connect to validation and benchmark hooks.
- Model router → Local runtime: can use · Portability examples can target local inference runtimes.
- Protocol bridge → Data services: connects to · MCP and A2A examples bridge to external service ecosystems.
- Memory systems → Data services: stores in · Graph-based memory uses external persistence and retrieval services.
- Agent loop → Model APIs: calls · Baseline agent execution depends on model providers.
- Prompt layer → Model APIs: calls · Prompt experiments ultimately route into model APIs.
- Tools & skills → Data services: uses · Skills and tools access APIs, databases, and other operational systems.
