Lesson 05: Artifacts, DAGs, And Gates

Lesson Goal

This lesson teaches three ideas that make AI workflows reliable:

• Artifacts: named outputs that later steps can use.
• DAGs: workflow graphs with a safe execution order.
• Gates: controlled stops for quality, risk, or human approval.

If you understand these three, you can read most agentic workflow diagrams.

1. Why Artifacts Matter

An artifact is a named output from a workflow step.

Without artifacts, a workflow depends on vague memory:

The model did some research earlier. Now ask it to write the final answer.

With artifacts, the workflow has explicit state:

research_notes -> draft_answer -> review_score -> final_answer

Artifacts help because they are:

• Inspectable: a human can read them.
• Testable: a checker can validate them.
• Reusable: another node can consume them.
• Traceable: the run record can show when they were produced.
• Governable: gates can block based on them.

2. Good Artifact Names

Good artifact names are specific and stable.

Weak names:

• output
• result
• text
• data
• thing

Better names:

• user_goal
• research_questions
• source_notes
• draft_answer
• quality_check
• approval_record
• final_answer

Beginner rule: if a downstream node depends on it, give it a real name.

3. Artifact Contracts

An artifact contract says what a node promises to produce.

Example:

node: draft_answer
consumes: research_summary
produces: draft_answer

For structured systems, the contract can be more detailed:

draft_answer:
  type: markdown
  required_sections:
    - summary
    - evidence
    - recommendation

Contracts reduce ambiguity. They also make quality checks easier.

4. What Is A DAG?

DAG means Directed Acyclic Graph.

Directed means arrows have direction:

A -> B -> C

Acyclic means no loops that trap execution:

Bad:
A -> B -> A

Graphs matter because many workflows are not simple straight lines.

capture_goal
  -> technical_research
  -> market_research
  -> synthesize
  -> draft
  -> review

The two research steps can run independently, then merge.

5. Reading A Workflow Graph

When you see a workflow graph, ask:

1. What starts the workflow?
2. What can run in parallel?
3. What artifacts does each node produce?
4. What depends on those artifacts?
5. Where can execution stop?
6. What is the final output?

Do not start by reading every implementation detail. First understand the shape.

6. Gates

A gate is a hard stop. It prevents the workflow from continuing until a condition is satisfied.

Examples:

• human_approval must be true before final output.
• quality_score must be at least 80.
• citations_present must be true.
• estimated_cost must be below budget.
• risk_tier must be low enough for automatic execution.

Gates turn vague instructions into enforceable control points.

7. Gate Types

8. Gates Are Not Errors

Beginners often see a blocked gate and think the workflow failed. Sometimes it did exactly what it should do.

draft created
review completed
approval required
workflow blocked

That is a safe pause, not a crash.

9. Hands-On: Agent With Gate

Run:

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

Find:

• The goal artifact.
• The course plan artifact.
• The tool check artifact.
• The gate node.
• The node that does not run because the gate blocks.

Then open the workflow file:

examples/03_agent_with_gate.json

Change the gate approval value from false to true, then run again. Observe how the final node becomes reachable.

10. Branches And Parallel Work

Workflows can branch when different steps do not depend on each other.

Example:

capture_goal
  -> research_technical
  -> research_business
  -> research_risks
  -> synthesize_all

Parallel branches are useful, but they create merge questions:

• What happens if one branch fails?
• What if two branches produce the same artifact name?
• What if one branch returns low confidence?
• Does the merge wait for all branches?

Good orchestration answers these questions explicitly.

11. Retry And Revision

Some gates should trigger revision instead of stopping forever.

draft_answer
  -> quality_check
  -> if pass: approval_gate
  -> if fail: revise_answer
  -> quality_check

Always add a retry limit:

maximum revisions: 2

Without a limit, the system can loop indefinitely.

12. Common Beginner Mistakes

Mistake 1: Using generic artifact names.

Correction: Name outputs based on their purpose.

Mistake 2: Creating circular dependencies.

Correction: Draw the graph and check that arrows move toward completion.

Mistake 3: Treating approval as a prompt instruction.

Correction: Use a real gate.

Mistake 4: Forgetting what happens after failure.

Correction: Decide whether the workflow stops, retries, routes to review, or returns a partial result.

Mistake 5: Letting parallel branches overwrite each other.

Correction: Give each branch distinct artifacts and define merge behavior.

13. Artifact And Gate Checklist

Before running a workflow, check:

• Every important output has a name.
• Every downstream dependency can find the artifact it needs.
• The graph has no cycles.
• Risky actions are behind gates.
• Failed quality checks have a defined route.
• Retry loops have limits.
• Human approval is recorded as an artifact.
• The final output depends on approved inputs.

14. Summary

Artifacts make outputs explicit. DAGs make execution order safe. Gates make risk and judgment enforceable. Together, they turn agentic behavior into a workflow that people can inspect, debug, and trust.

Exercises

Exercise 1: Run The Gated Workflow

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

Find the blocked node and explain why it stopped.

Exercise 2: Approve The Gate

Open ../../examples/03_agent_with_gate.json and change:

"approved": false

to:

"approved": true

Run the workflow again and observe the final node.