How agulli/atlas-agents works
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: atlas_v03.py Tools & skills · config.py Config · benchmark.py Model router · atlas_v01.py Agent loop
Components 19
Shared foundation
Common config, runtime envelope, and reusable skill assets used across chapters.
- Config · Environment and provider configuration shared by the examples.
shared/config.py - Skills helper · Common code for loading and using shared skills.
shared/skills.py - Skill library · Reusable Markdown skill definitions used as declarative capability assets.
shared/declarative_skills - Runtime envelope · Repository-wide Python dependencies and environment variable template.
requirements.txt
Core patterns
Chapter 1 to 7 cover the main agent architecture patterns.
- Agent loop · Minimal ReAct-style agent baseline and its online variants.
ch01_react_from_scratch/atlas_v01.py - Prompt layer · Prompt shaping, routing, injection defense, and A/B testing.
ch02_prompt_architecture - Tools & skills · Tool invocation, skill discovery, API skills, and database skills.
ch03_tools_and_skills/atlas_v03.py - Handoff router · Triage, escalation chains, and context-preserving routing between specialists.
ch04_handoffs/triage.py - State graphs · Persisted agent workflows with approval gates, fan-out, and debugging.
ch05_state_graphs/code_review_agent.py - Crew system · Role-based crews with coordinators, specialists, memory, and jury roles.
ch06_multi_agent/newsletter_crew.py - Model router · 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 · MCP servers and A2A discovery/rendering integrations.
ch08_mcp_a2a/mcp_knowledge_server.py - Skill packs · Large catalog of standalone SKILL.md capability definitions.
ch09_agent_skills/skills - Claude workflow · Claude Code-oriented validation, benchmarking, and CI-style automation.
ch10_claude_code_antigravity/AGENTS.md - Memory systems · 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 · Hosted LLM providers used by the online examples.
- Local runtime · Local inference/runtime such as Ollama used by portability examples.
- Data services · GitHub, Neo4j, and other service integrations referenced by online modules.
- CI hooks · Validation and execution feedback surfaces for autonomous coding workflows.
Connections 23
- 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.