MESHFLOW_MOCK=1 python3 hands_on/00_setup.py30 to 45 minutes to read and absorb. You will not write code in this lesson. You will build the mental model you need before code makes sense.
Before using MeshFlow-style orchestration, build the right mental stack. Each layer below depends on the one above it. If you skip a layer, the next one will feel arbitrary.
AI
-> Generative AI
-> LLMs
-> Prompts and context
-> Tools and memory
-> Agents
-> Workflows
-> Orchestration
-> MeshFlowThis is not just a vocabulary list. It is an explanation of how AI systems actually get built in production: starting from a raw model and adding structure layer by layer until the system is controllable, auditable, and safe.
Most developers approach AI top-down: they start with a framework and try to understand it by using it. That works if the framework is deterministic and familiar. Orchestration frameworks for AI are neither.
AI model behavior is probabilistic. A node may return a different answer every time it runs. That means the framework around it has to handle partial failure, retry logic, approval gates, and audit traces in ways that no traditional software framework does.
If you start with orchestration too early, the graph syntax feels arbitrary. You memorize commands without understanding what problem they solve.
If you start with the foundations, orchestration becomes obvious. You will reach for it naturally because you have already felt the pain of uncontrolled model calls.
The rule is simple:
Understand a problem before you learn its solution.What it is: Software that performs tasks that normally require human-like judgment. Prediction, classification, ranking, detection, and generation are all AI tasks.
What it is not: Consciousness, understanding, or certainty.
Why it matters here: Everything below is AI. Knowing the category stops you from over-anthropomorphizing the model.
Key examples:
What it is: AI that creates new content rather than labeling or ranking existing content.
What distinguishes it from traditional AI: The output is content, not a prediction or label.
Key examples:
Why it matters here: MeshFlow orchestrates generative AI systems. The outputs of those systems are open-ended text or structured data, not simple predictions. That open-endedness is exactly why orchestration is needed: generated content must be checked, verified, and logged.
What it is: A large language model is a generative AI model specifically trained to work with text. You give it text input. It produces text output.
What makes it "large": The model has billions of parameters, trained on enormous corpora of text from books, code, documentation, and the web.
What it does:
input text (called a prompt) -> model -> output text (called a completion)What it does not automatically do:
All of these must be added by the system built around the model.
Why this matters here: Understanding what an LLM cannot do on its own is the clearest explanation for why orchestration exists.
What a prompt is: The input text you send to an LLM. In a simple chatbot, that is just the user's message.
What context is: In production systems, a prompt is much larger. Context is everything the model sees at inference time:
system instructions
+ developer instructions
+ conversation history
+ retrieved documents
+ tool descriptions
+ tool results
+ user preferences
+ workflow artifacts
+ the user's questionThe model does not remember previous runs. Every call starts fresh. The only thing the model knows about previous steps is what you include in context.
Why this matters here: MeshFlow workflows pass artifacts from one step to the next by including them in context. If you do not understand context, you will not understand how information flows through a workflow.
The key distinction:
Context is what the model sees in a single call.
Memory is a system that retrieves and inserts relevant past information into context.They are not the same thing. An LLM has neither by default. Your system must provide both.
What tools are: Functions that a model can be given permission to call. The model outputs a structured request to use a tool, the system executes it, and the result is inserted back into context.
Common tools:
What memory is: A system that stores information from previous interactions and retrieves relevant pieces when they are needed for the current call.
Types of memory in practice:
| Type | What it stores | How it is retrieved |
|---|---|---|
| Conversation history | Recent messages | Appended to context directly |
| Episodic memory | Summaries of past sessions | Semantic search |
| Semantic memory | Facts, documents, knowledge | Embedding similarity search |
| Working memory | Current step state | Workflow artifact system |
Why this matters here: MeshFlow workflows can route tool results and artifact outputs as inputs to later nodes. Understanding tools and memory lets you design workflows that know what they have already done.
What an agent is: A system that uses an LLM to pursue a goal by choosing actions, calling tools, observing results, and deciding the next step — iteratively, without requiring a human to direct each step.
The agent loop:
1. Receive goal
2. Think about next action
3. Call a tool
4. Observe the tool result
5. Update understanding
6. Decide: done or next action?
7. If not done, go to step 2What makes an agent different from a plain LLM call:
| Plain LLM call | Agent |
|---|---|
| One input, one output | Goal-directed iteration |
| No tools | Can call tools |
| No state | Maintains state across steps |
| Human drives each step | Model drives its own steps |
| Stateless | Has a loop |
The tradeoff: Agents are more capable than single LLM calls, but they are also less predictable. An agent can loop too long, call tools in unexpected orders, or take wrong actions.
Why this matters here: MeshFlow can run agent nodes inside a governed workflow. You get the flexibility of agent behavior inside the structure of a controlled process.
What a workflow is: A defined sequence or graph of steps, where each step produces a named output, and later steps can depend on earlier outputs.
The difference from agents:
An agent decides what action to take next.
A workflow defines what steps exist and in what order they can run.Why workflows matter:
A simple example:
fetch_policy_document
-> summarize_policy (depends on: fetch_policy_document)
-> extract_action_items (depends on: summarize_policy)
-> human_review_gate (blocks until approved)
-> publish_summary (depends on: human_review_gate)Each arrow is an explicit dependency. Each step produces a named artifact. Each artifact is the contract between steps.
What orchestration is: The system that manages workflow execution. It handles:
Why orchestration is a separate concern from the model: Models are probabilistic. Orchestration is deterministic. The orchestration layer provides guarantees the model cannot: that steps run in order, that dependencies are met, that every action is logged, and that a human can review the full trace.
What orchestration is not: A chain of raw API calls you manage yourself. That approach works for simple, one-step use cases. It breaks down when steps have dependencies, when failures need recovery, or when a human must approve before an action executes.
What MeshFlow is: A graph-based workflow orchestration model for AI systems. It provides:
How it fits the stack:
MeshFlow = workflow graph + artifact system + gate model + trace logWhy MeshFlow and not a plain prompt chain:
| Plain prompt chain | MeshFlow |
|---|---|
| Steps implicit | Steps explicit |
| No artifact names | Named, typed artifacts |
| No dependency tracking | DAG with declared edges |
| No human gates | Gate nodes |
| No trace | Full run trace |
| Fails silently | Fails at the node level with a trace |
Think about what happens when you want an AI system to research a topic, draft a document, review it, and publish it.
Option 1: One big prompt
"Research renewable energy policy changes in 2025, compare them with the
previous year, write a 1000-word executive summary, check it for accuracy,
and prepare the final version for publication."Problems:
Option 2: A MeshFlow-style workflow
research_step
-> comparison_step (consumes: research artifact)
-> draft_step (consumes: comparison artifact)
-> quality_check_step (consumes: draft artifact)
-> human_approval_gate
-> publish_step (executes only after human approves)Gains:
outputs were produced.
This is not just better software engineering. It is the difference between an AI system you can reason about and one you cannot.
| Phase | Lessons | What You Build |
|---|---|---|
| 0: Orientation | 00 | This mental model |
| 1: Foundations | 01, 02, 03 | Understanding of LLMs, context, memory, tools, agents, workflows |
| 2: MeshFlow Core | 04, 05 | Ability to read and write workflow graphs with artifacts and gates |
| 3: Agentic Workflows | 06, 07 | Debugging skills, trace reading, observability |
| 4: Compare And Choose | references | Informed view of where MeshFlow fits vs. alternatives |
| 5: Final Project | 08 | A complete end-to-end governed workflow |
Read in order. Each lesson assumes the previous one.
Lesson 01: AI, Generative AI, And LLMs You will build the bottom of the stack: understand what an LLM is and is not, run the simplest possible one-node workflow, and feel the difference between a raw model call and a governed step.
Lesson 02: Context, Memory, And Tools You will understand what the model actually sees at inference time, how memory systems work, and how tools extend what an LLM can do.
Lesson 03: Agents And Workflows You will understand the agent loop, when agents are better than a single prompt, and when a structured workflow is better than an open-ended agent.
Lesson 04: What Is MeshFlow You will understand the MeshFlow model: nodes, edges, artifact contracts, gate nodes, and the run trace.
Lesson 05: Artifacts, DAGs, And Gates You will understand directed acyclic graphs for workflow modeling, what an artifact contract is, and how gate nodes enforce approval or conditions.
Lesson 06: Agent Workflow Walkthrough You will walk through a complete agentic workflow step by step, reading every node, every artifact, and every gate.
Lesson 07: Debugging, Traces, And Observability You will learn how to read a run trace, locate the source of a failure, and instrument a workflow for production.
Lesson 08: Final Project You will design and run a complete governed workflow: research, extract, draft, quality-check, approve, and publish.
Mistake 1: Assuming the model has memory. It does not. Every call starts with an empty context window. Memory is a system built around the model that retrieves and inserts relevant past information.
Mistake 2: Assuming the model knows today's date, your private data, or current events. It does not. Everything the model knows must be explicitly included in the prompt or retrieved via a tool.
Mistake 3: Treating a chatbot as equivalent to an agent. A chatbot is an interface. An agent is a goal-directed loop. A chatbot may or may not use an agent internally.
Mistake 4: Treating orchestration as unnecessary overhead. Orchestration overhead is real. For a one-step proof of concept, it is not needed. For any system where steps have dependencies, humans must approve, or auditors need a log, it is essential.
Mistake 5: Skipping foundation layers and jumping to framework commands. MeshFlow YAML or JSON will make sense only after you understand what nodes, artifacts, and gates represent. Read the foundations before touching the config.
Before moving to Lesson 01, be able to answer all of the following without notes. These are not trick questions. If you cannot answer them, re-read the relevant section.
Section 1: Vocabulary
Section 2: Distinctions
Section 3: Motivation
The three questions from the original version of this lesson are answered here so you know what a complete answer looks like.
What is the difference between an LLM and an AI agent?
An LLM is a model that takes text as input and produces text as output. It does not take actions, remember past calls, or pursue goals across multiple steps.
An AI agent is a system that uses an LLM to pursue a goal by choosing actions, calling tools, observing results, and repeating until the goal is met. The LLM is one component inside the agent system.
Why is context not the same thing as memory?
Context is what the model sees in a single call: everything in the prompt window at inference time. It is temporary. When the call ends, the context is gone.
Memory is an external storage system that persists information between calls and retrieves relevant pieces to insert into future context. Without a memory system, each LLM call starts with no knowledge of previous calls.
Why do production AI workflows need orchestration?
Because production AI systems must do things that a raw model call cannot guarantee:
Orchestration provides the deterministic control layer that wraps around the probabilistic model layer.
| Term | Short definition |
|---|---|
| AI | Software that performs tasks requiring human-like judgment |
| Generative AI | AI that creates new content rather than labeling or predicting |
| LLM | Large language model: generative AI for text |
| Prompt | The text input to an LLM |
| Context | Everything the model sees in a single call |
| Memory | External storage that retrieves past information into context |
| Tool | A function a model can request the system to call |
| Agent | A goal-directed loop that uses an LLM to choose and execute actions |
| Agent loop | The cycle: think → act → observe → decide → repeat |
| Workflow | A declared graph of steps with named dependencies |
| Artifact | A named, versioned output produced by a workflow step |
| Dependency | A declared relationship where one step requires another's artifact |
| Gate | A node that blocks execution until a condition or approval is met |
| Orchestration | The system that schedules, traces, and governs workflow execution |
| DAG | Directed acyclic graph: a graph with no cycles, used to model workflows |
| Trace | A log of every step that ran, with inputs, outputs, and timestamps |
| MeshFlow | A graph-based workflow orchestration model for governed AI systems |
When you can answer every checkpoint question above without notes, continue to Lesson 01.
Lesson 01: AI, Generative AI, And LLMs
If any question blocked you, use the Key Terms Reference above and re-read the relevant layer section. Do not move forward with gaps. The layers build on each other.
Open ../../COURSE_MAP.md and identify the five phases of the course.
In your own words, explain this stack:
AI -> Generative AI -> LLM -> Agent -> Workflow -> Orchestration -> MeshFlowRun:
python3 -m src.mini_meshflow compile examples/01_basic_llm.jsonWrite down what the command reports.