Lesson 06: Agent Workflow Walkthrough

Lesson Goal

This lesson walks through a complete agent workflow step by step. The goal is to make the execution feel concrete. You should be able to predict what each node does before you run it.

We will use:

examples/03_agent_with_gate.json

1. The Workflow Shape

The workflow looks like this:

capture_goal
  -> draft_plan
  -> check_plan
  -> human_approval
  -> final_answer

Plain English version:

1. Capture what the user wants.
2. Ask an agent to draft a plan.
3. Check the plan with a tool.
4. Stop for human approval.
5. Finalize only if approved.

2. Why This Is Agentic

The draft_plan step is an agent node. It receives the goal and creates a plan. In a real system, that agent might:

• Break the goal into steps.
• Decide whether it needs tools.
• Ask for clarification.
• Compare options.
• Produce a structured plan.

In this tutorial runner, agent behavior is simulated so you can focus on the workflow shape.

3. Why This Is Governed

The agent does not publish directly. It produces an artifact:

course_plan

Then another node checks it. Then a gate blocks finalization until approval.

This matters because agents are flexible but not always predictable. A workflow adds boundaries.

4. Step-By-Step Execution

Step 1:

capture_goal
type: prompt
produces: goal

This creates the first artifact. Everything downstream depends on a clear goal.

Step 2:

draft_plan
type: agent
consumes: goal
produces: course_plan

The agent uses the goal and drafts a plan.

Step 3:

check_plan
type: tool
tool: word_count
consumes: course_plan
produces: plan_word_count

The tool checks something measurable about the plan. Real checks could include policy review, citation review, rubric scoring, or schema validation.

Step 4:

human_approval
type: gate
approved: false

The workflow stops here until approval is present.

Step 5:

final_answer
type: prompt
consumes: course_plan
produces: final_tutorial

This step runs only after the gate passes.

5. Run The Workflow

Run:

python3 -m src.mini_meshflow run examples/03_agent_with_gate.json

Expected behavior:

• The first nodes run.
• The gate blocks.
• The final output is not produced.

That is correct. The workflow is protecting the final step.

6. Approve And Run Again

Open:

examples/03_agent_with_gate.json

Find the gate node and change:

"approved": false

to:

"approved": true

Run again:

python3 -m src.mini_meshflow run examples/03_agent_with_gate.json

Now the final node should run.

7. What To Observe In The Output

Look for three sections:

• Artifacts: named outputs from nodes.
• Memory: stored values, if the workflow uses memory.
• Trace: execution record.

Ask:

• Which artifacts exist before the gate?
• Which artifact appears only after approval?
• Which node produced each artifact?
• What does the trace say about the blocked or approved gate?

8. How To Extend This Workflow

Beginner extension:

capture_goal
  -> draft_plan
  -> check_plan
  -> revise_plan
  -> human_approval
  -> final_answer

Intermediate extension:

capture_goal
  -> draft_plan
  -> check_plan
  -> estimate_cost
  -> human_approval
  -> final_answer

Advanced extension:

capture_goal
  -> researcher_agent
  -> writer_agent
  -> reviewer_agent
  -> quality_gate
  -> human_approval
  -> final_answer

Each extension should add a clear artifact, not just another hidden prompt.

9. What A Real Production Version Adds

A production agent workflow might add:

• Real LLM provider calls.
• Real tool schemas.
• Input validation.
• Durable memory.
• Authentication.
• Cost limits.
• Retry policies.
• Human review UI.
• Observability dashboard.
• Audit logs.

The tutorial runner is intentionally small. It teaches the skeleton before the industrial machinery.

10. Common Beginner Mistakes

Mistake 1: Skipping the check step.

Correction: Add at least one measurable review before approval.

Mistake 2: Letting the agent approve itself.

Correction: Use a separate gate or reviewer.

Mistake 3: Publishing from the agent node.

Correction: Make the agent produce a draft artifact, then publish later.

Mistake 4: Forgetting to inspect the trace.

Correction: Read the trace after every run until the workflow feels predictable.

11. Summary

This workflow shows the core pattern of governed agent design:

goal -> agent draft -> check -> gate -> final output

The agent provides flexible reasoning. The workflow provides structure, inspection, and control.

Exercises

Exercise 1: Map Inputs And Outputs

For each node in ../../examples/03_agent_with_gate.json, write:

Open the JSON file directly and fill the table from the node definitions. Do not run the workflow yet — read the structure first.

Expected result: a table with five rows. Compare against the answers in answers.md only after you have filled it in yourself.

Exercise 2: Add A Review Instruction

Open ../../examples/03_agent_with_gate.json and add a specific instruction to the review_plan node. For example:

"Check that the plan mentions at least three distinct sources and does not

recommend any action that requires budget approval."

Run the workflow:

python3 -m src.mini_meshflow run examples/03_agent_with_gate.json

Answer:

• Did the review output change?
• Did the gate pass or block?
• What would you change in the instruction to make the gate more likely to pass?

Exercise 3: Change The Gate Condition

Open the workflow file and change "approved": false to "approved": true. Run the workflow again.

Answer:

• Which node ran that did not run before?
• What artifact did it produce?
• Compare the two trace outputs side by side. What is the only structural

difference?

Now change "approved": true back to "approved": false.

Exercise 4: Trace Walk-Through

Run the workflow with the gate blocked:

python3 -m src.mini_meshflow run examples/03_agent_with_gate.json

Walk through the trace output and answer for each node:

The goal is to read the trace as a story: what ran, what was blocked, and what never had a chance to run because an upstream node did not complete.

Exercise 5: Add A Second Gate

Design (do not code) a second gate that fires earlier in the workflow — before the agent node runs. Describe:

• What condition would this gate check?
• What artifact would it evaluate?
• What would happen to the agent and all downstream nodes if this early gate

blocked?

A good answer names a realistic condition (for example, "topic is within allowed subject areas" or "input length is under 500 tokens") and explains the benefit of catching it early rather than after the agent has already spent compute.