The Problem

Developers new to agentic systems lack a single, executable reference that shows how a model, a tool set, and a simple control loop combine into a working agent. Existing blogs and SDK docs are fragmented, making it hard to prototype quickly or to understand the minimal runtime needed for a production‑grade agent.

What This Does

The repository contains a small set of Python sketches that demonstrate incremental agent design.

  • tutorials/agent-loop/v0_bash_agent.py and v0_bash_agent_mini.py implement a bare‑bones loop that sends prompts to a model and executes returned shell commands.
  • v1_basic_agent.py adds a minimal skill registry loaded from tutorials/agent-loop/skills.
  • v2_todo_agent.py, v3_subagent.py, and v4_skills_agent.py illustrate structured planning, subagent orchestration, and skill‑based execution.
  • The skills/agent-builder and skills/code-review directories ship a SKILL.md file and a small Python helper (minimal-agent.py) that expose a standard skill interface.

These examples are not production code, but they provide a clear progression from an untethered model to a modular, skill‑aware agent.

How It Is Wired

Entry point – tutorials/agent-loop/v0_bash_agent.py is the only script that can be run directly.

  • main() reads a prompt, calls model_response() from minimal-agent.py, and parses the response.
  • Parsed actions are forwarded to subprocess.run(); the output is fed back into the loop.
  • The skill‑based examples replace the direct call to subprocess with a lookup into the skill registry (skills/__init__.py), which imports the skill modules listed in the SKILL.md files.
  • Each skill module exposes a single function (e.g., run()) that the registry dispatches to.
  • The subagent example (v3_subagent.py) creates a new Python process that runs its own loop and communicates via file I/O, demonstrating a lightweight subagent pattern.

The wiring is intentionally linear: prompt → model → action → subprocess / skill → feedback → prompt. There is no external state persistence beyond the environment and the current process memory.

How To Use It

Setup

git clone https://github.com/moses-y/agentic-engineering-handbook
cd agentic-engineering-handbook
pip install -r tutorials/agent-loop/requirements.txt

Configuration Copy the example environment file and set the keys:

cp tutorials/agent-loop/.env.example .env
# edit .env and set OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

Running

python tutorials/agent-loop/v0_bash_agent.py

Interact by typing natural language tasks; the script will request the model, execute the suggested shell commands, and print the result.

Real‑World Use

An internal research team can use v3_subagent.py as a lightweight orchestration layer: the main agent plans, then delegates sub‑tasks to specialized subagents that run in isolated environments. The subagents return results via a shared file or pipe, allowing the main agent to stitch the outputs together.

Code Health & Issues

  • Tests: 0/10 – the repo contains no unit or integration tests.
  • CI/CD: 0/1 – no GitHub Actions or other pipeline configuration is present.
  • Lockfile: 0/1 – requirements.txt is used without a pip‑freeze lock.
  • Reproducibility: Medium – installing from requirements.txt can pull newer versions of dependencies, potentially breaking the examples.
  • Documentation: 2/3 – the README provides an outline; most markdown files are tutorials, but API references are minimal.

The Bottom Line

The handbook offers a clear, executable path from a raw model to a modular agent, suitable for learning and prototyping. It lacks automated testing, CI, and reproducible dependency locking, so teams should treat the examples as educational scaffolds rather than production components. Developers who need a quick proof‑of‑concept or a teaching aid will find the repo valuable; those looking for battle‑tested production code should supplement it with their own infrastructure and testing layers.