ACAgentic Craft

Path

Learning roadmap

Foundation → Builder → Production → Platform/Agent OS. Filter by role and experience; completion stays in local storage. The textual version below remains available without JavaScript.

Foundation

  1. Agentic AI in plain language

    Goals, tools, observations, and stops—without marketing jargon.

  2. What is an agent?

    Define HazelJS agents via @Agent, @Tool, and AgentRuntime.execute.

    Depends on foundations-plain

  3. Agent vs workflow vs chatbot

    Choose the right control-flow model for the job.

    Depends on foundations-agent

  4. When not to use an agent

    Prefer @hazeljs/ai or flow until observation-driven branching is required.

    Depends on foundations-compare

  5. AgentRuntime mental model

    Context assembly, ToolRegistry, budgets, checkpoints, stop reasons.

    Depends on foundations-when-not

  6. Core glossary pass

    Internalize agent, tool, skill, MCP, memory, and state.

    Depends on foundations-agent

  7. Augmented LLM pattern

    Prefer a bounded model call before an open agent loop.

    Depends on foundations-runtime-model

Builder

  1. Scaffold your first HazelJS agent

    Install packages, enable decorators, mock LLM, verify runtime.

    Depends on pattern-augmented-llm

  2. Build a tool-using agent loop

    Ops Desk: @Agent, lookupOrder, execute, read one full loop.

    Depends on builder-scaffold

  3. Guide: first tool-using agent

    Ship a working artifact with tests for stop conditions.

    Depends on builder-tool-loop

  4. Bounded runs and stop reasons

    maxSteps, loop.maxIterations, and why prompts cannot cap cost.

    Depends on builder-tool-loop

  5. Context windows as scarce resources

    Truncate observations; turn RAG/memory on only when needed.

    Depends on builder-budgets

  6. Safe writes, approvals, and HITL

    requiresApproval, PolicyEngine, durableSuspend for refunds.

    Depends on builder-context

  7. Golden tests with describeAgent

    Lock tool behavior in CI before prompt merges.

    Depends on builder-hitl-writes

  8. Observability signals for agent decisions

    executionId, timelines, stop reasons, budget alerts.

    Depends on builder-goldens

  9. Hazel CLI agent ops

    doctor, DNA smoke, logs, runs—stubs vs app execute.

    Depends on builder-observability

  10. Memory layers pattern

    Separate working context, session memory, and durable state.

    Depends on builder-context

  11. Evaluator–optimizer pattern

    Add critique loops only where quality justifies cost.

    Depends on builder-tool-loop

  12. Idempotent tool execution

    Keys and dedupe so durable resume cannot double-write.

    Depends on builder-hitl-writes

  13. Guide: Skillgate OpenAPI → ToolRegistry

    fromOpenApi, register, report(), optional MCP export.

    Depends on builder-tool-loop

  14. Track: Context Engineering

    Assemble context, RAG, and truncation policies.

    Depends on builder-context

  15. Track: Tools, Skills, and MCP

    Tool contracts and Skillgate/MCP integration styles.

    Depends on prod-skillgate-guide

  16. Track: Memory and State

    Memory layers vs durable AgentRun state.

    Depends on c-context, builder-memory

Production

  1. Demo to production checklist

    Capstone go/no-go: reliability, security, evals, and ops.

    Depends on builder-guide-first-agent, builder-cli

  2. Guide: demo to production

    Harden a demo with observability, approvals, and recovery.

    Depends on prod-checklist

  3. Human approval gate

    Suspend risky actions without breaking the run model.

    Depends on prod-checklist

  4. Durable agent run

    Checkpoint, recover, and resume after failures.

    Depends on prod-hitl, builder-idempotent

  5. Compensating action

    Saga/flow undo paths for partial agent side effects.

    Depends on prod-durable

  6. Prompt vs workflow vs graph vs loop

    Evidence-based control-flow comparison for architecture reviews.

    Depends on foundations-compare

  7. Guide: evaluation harness

    describeAgent + @hazeljs/eval gates in CI.

    Depends on prod-checklist

  8. Guide: human approval without breaking the run

    durableSuspend + approveAndResume with durable stores.

    Depends on prod-hitl

  9. Guide: durable execution and recovery

    Checkpoints, leases, crash-resume, idempotent writes.

    Depends on prod-durable, prod-hitl-guide

  10. Bounded autonomy pattern

    Capabilities, PolicyEngine, maxSteps, HITL ceilings.

    Depends on prod-checklist

  11. Budget-aware execution

    RunBudget maxTokens/maxCostUsd hard stops.

    Depends on prod-bounded

  12. Guide: secure MCP and agent tools

    Curation, guardrails, Skillgate, PolicyEngine.

    Depends on prod-bounded

  13. Agent sandbox (isolation)

    Honest isolation via curation, tenants, policy—no vaporware OS sandbox.

    Depends on prod-secure-mcp

  14. MCP vs Skillgate vs direct API

    HazelJS-native integration style comparison.

    Depends on prod-skillgate-guide

  15. Track: Evals and Reliability

    describeAgent suites and CI eval gates.

    Depends on prod-eval-harness

  16. Track: Observability and Cost

    Inspector timelines and RunBudget alerts.

    Depends on builder-observability, prod-budget

  17. Track: Security and Governance

    Guardrails, auth/CASL, and agent policy.

    Depends on prod-secure-mcp, prod-bounded

  18. Track: Durable Execution and HITL

    Checkpoints, leases, and production HITL.

    Depends on prod-durable-guide, prod-hitl-guide

Platform / Agent OS

  1. Design an agent manifest

    Declare identity, skills, policy, and SLOs as a contract.

    Depends on prod-durable, prod-eval-harness

  2. Agent OS layered model

    Control plane, DNA, runtime, skill gateway, durable kernel.

    Depends on platform-manifest

  3. Framework vs runtime vs Agent OS

    Clarify category boundaries before buying or building platforms.

    Depends on platform-agent-os

  4. Track: Orchestration and Multi-Agent

    AgentGraph, Supervisor, Delegate, and flow vs multi-agent.

    Depends on foundations-runtime-model

  5. Track: Deployment and Agent Operations

    Workers, stores, CLI ops, DNA runbooks.

    Depends on c-obs, c-durable, builder-cli

  6. Track: Agent OS Architecture

    Layer map and adoption sequence capstone.

    Depends on c-orchestration, c-security, platform-agent-os

  7. Design a production Agent Runtime

    Flagship lab: Meridian Ops — App, DNA, Store, platform, and AgentRuntime execute.

    Depends on prod-guide, platform-agent-os, c-agent-os-arch

  8. Production Agent Runtime Blueprint

    Compressed Meridian five-layer anatomy for architecture reviews.

    Depends on platform-meridian-runtime

  9. Pattern: Router

    Conditional routing to specialists.

    Depends on c-orchestration

  10. Pattern: Supervisor and specialists

    createSupervisor / multi-agent delegation.

    Depends on c-pattern-router

Canonical textual roadmap

Indexable and accessible without client filters.

foundation

  1. Agentic AI in plain language — Goals, tools, observations, and stops—without marketing jargon.
  2. What is an agent? — Define HazelJS agents via @Agent, @Tool, and AgentRuntime.execute.
  3. Agent vs workflow vs chatbot — Choose the right control-flow model for the job.
  4. When not to use an agent — Prefer @hazeljs/ai or flow until observation-driven branching is required.
  5. AgentRuntime mental model — Context assembly, ToolRegistry, budgets, checkpoints, stop reasons.
  6. Core glossary pass — Internalize agent, tool, skill, MCP, memory, and state.
  7. Augmented LLM pattern — Prefer a bounded model call before an open agent loop.

builder

  1. Scaffold your first HazelJS agent — Install packages, enable decorators, mock LLM, verify runtime.
  2. Build a tool-using agent loop — Ops Desk: @Agent, lookupOrder, execute, read one full loop.
  3. Guide: first tool-using agent — Ship a working artifact with tests for stop conditions.
  4. Bounded runs and stop reasons — maxSteps, loop.maxIterations, and why prompts cannot cap cost.
  5. Context windows as scarce resources — Truncate observations; turn RAG/memory on only when needed.
  6. Safe writes, approvals, and HITL — requiresApproval, PolicyEngine, durableSuspend for refunds.
  7. Golden tests with describeAgent — Lock tool behavior in CI before prompt merges.
  8. Observability signals for agent decisions — executionId, timelines, stop reasons, budget alerts.
  9. Hazel CLI agent ops — doctor, DNA smoke, logs, runs—stubs vs app execute.
  10. Memory layers pattern — Separate working context, session memory, and durable state.
  11. Evaluator–optimizer pattern — Add critique loops only where quality justifies cost.
  12. Idempotent tool execution — Keys and dedupe so durable resume cannot double-write.
  13. Guide: Skillgate OpenAPI → ToolRegistry — fromOpenApi, register, report(), optional MCP export.
  14. Track: Context Engineering — Assemble context, RAG, and truncation policies.
  15. Track: Tools, Skills, and MCP — Tool contracts and Skillgate/MCP integration styles.
  16. Track: Memory and State — Memory layers vs durable AgentRun state.

production

  1. Demo to production checklist — Capstone go/no-go: reliability, security, evals, and ops.
  2. Guide: demo to production — Harden a demo with observability, approvals, and recovery.
  3. Human approval gate — Suspend risky actions without breaking the run model.
  4. Durable agent run — Checkpoint, recover, and resume after failures.
  5. Compensating action — Saga/flow undo paths for partial agent side effects.
  6. Prompt vs workflow vs graph vs loop — Evidence-based control-flow comparison for architecture reviews.
  7. Guide: evaluation harness — describeAgent + @hazeljs/eval gates in CI.
  8. Guide: human approval without breaking the run — durableSuspend + approveAndResume with durable stores.
  9. Guide: durable execution and recovery — Checkpoints, leases, crash-resume, idempotent writes.
  10. Bounded autonomy pattern — Capabilities, PolicyEngine, maxSteps, HITL ceilings.
  11. Budget-aware execution — RunBudget maxTokens/maxCostUsd hard stops.
  12. Guide: secure MCP and agent tools — Curation, guardrails, Skillgate, PolicyEngine.
  13. Agent sandbox (isolation) — Honest isolation via curation, tenants, policy—no vaporware OS sandbox.
  14. MCP vs Skillgate vs direct API — HazelJS-native integration style comparison.
  15. Track: Evals and Reliability — describeAgent suites and CI eval gates.
  16. Track: Observability and Cost — Inspector timelines and RunBudget alerts.
  17. Track: Security and Governance — Guardrails, auth/CASL, and agent policy.
  18. Track: Durable Execution and HITL — Checkpoints, leases, and production HITL.

platform

  1. Design an agent manifest — Declare identity, skills, policy, and SLOs as a contract.
  2. Agent OS layered model — Control plane, DNA, runtime, skill gateway, durable kernel.
  3. Framework vs runtime vs Agent OS — Clarify category boundaries before buying or building platforms.
  4. Track: Orchestration and Multi-Agent — AgentGraph, Supervisor, Delegate, and flow vs multi-agent.
  5. Track: Deployment and Agent Operations — Workers, stores, CLI ops, DNA runbooks.
  6. Track: Agent OS Architecture — Layer map and adoption sequence capstone.
  7. Design a production Agent Runtime — Flagship lab: Meridian Ops — App, DNA, Store, platform, and AgentRuntime execute.
  8. Production Agent Runtime Blueprint — Compressed Meridian five-layer anatomy for architecture reviews.
  9. Pattern: Router — Conditional routing to specialists.
  10. Pattern: Supervisor and specialists — createSupervisor / multi-agent delegation.