Anatomy of Agentic Workflows

Workflow patterns, critic loops, routing, and execution.

Agentic Workflows

Orchestrating multiple AI agents, tools, and humans to ship real outcomes — reliably.

TL;DR

An agentic workflow chains plans, tools, sub-agents, and humans to complete a goal.
Core building blocks: Planner → Executor → Critic → Memory → Tools → Human Gate.
Patterns: sequential, parallel fan-out, router, reflect-and-retry, plan-and-act.
Add observability and kill-switches before scaling.

Why this matters

A single LLM call is a calculator. An agentic workflow is an assembly line — predictable, observable, and tunable. It's how AI moves from "demo" to "production".

Bottom line: The workflow, not the model, is the real product.

The Big Picture

Bottom line: Plan → act → check → (loop) → ship.

Core Roles

Role	Purpose
Planner	Decomposes the goal into steps
Executor	Runs steps; calls tools
Critic / Validator	Checks each step's output
Memory	Short-term + long-term context
Tools / MCP	External capabilities
Subagents	Specialists for sub-tasks
Human Gate	Approval before risky actions

Workflow Patterns

1. Sequential pipeline

goal → step1 → step2 → step3 → done

2. Parallel fan-out

            ┌─ analyze
goal ─ plan ┼─ test
            └─ document

3. Router (pick the right agent)

goal → router → @code-reviewer | @security-auditor | @docs-writer

4. Reflect-and-retry

attempt → critic → (fail) → reflect → retry → critic → done

5. Plan-and-act (ReAct)

Loop of Thought → Action → Observation until done.

Step-by-Step Setup

1. Define the goal in plain English

"Ship a tested, reviewed fix for issue #1234."

2. Decompose into a plan (`plan.yml`)

goal: "Fix issue #1234"
steps:
  - id: triage
    agent: bug-triage
    output: triage_report
  - id: tests
    agent: test-writer
    depends_on: [triage]
  - id: implement
    agent: claude-code
    depends_on: [tests]
  - id: review
    agent: code-reviewer
    depends_on: [implement]
  - id: human_gate
    type: approval
    depends_on: [review]
  - id: ship
    type: merge_pr
    depends_on: [human_gate]

3. Wire memory

"memory": {
  "short_term": { "type": "in_session" },
  "long_term":  { "type": "vector_store", "index": "project-memory" }
}

4. Add critics / validators

critics:
  - name: tests_pass
    rule: "exit_code == 0"
  - name: coverage
    rule: "coverage >= 0.8"
  - name: no_secrets
    rule: "secret_scan == clean"

5. Run & observe

claude workflow run plan.yml --observe

Variants for Different Team Settings

👤 Solo

Sequential, no human gate. Critic = your own eyes.

👥 Small team

Add a @code-reviewer critic + Slack notification on completion.

🏢 Enterprise

Human gates on every risky step.
Full audit trail to SIEM.
Kill-switch env var (CLAUDE_WORKFLOW_STOP=1).
Rate limits + budget caps.

limits:
  max_tokens_per_run: 200000
  max_cost_usd: 5.00
  max_runtime_minutes: 30

🌍 Open-source

Publish workflows as templates in a community repo.
Document expected inputs/outputs.

Bottom line: Same skeleton, escalating governance.

Anatomy of a Single Step

- id: review
  agent: code-reviewer
  input: { branch: feature/fix-1234 }
  tools: [Read, Bash, Grep]
  timeout: 120s
  retries: 2
  critics: [no_high_severity_issues]
  on_fail: rollback
  on_success: notify_slack

Common Patterns & Recipes

Pattern 1 — Self-check loop

- id: write_code
  agent: claude-code
- id: critique
  agent: code-reviewer
  on_fail: { goto: write_code, max: 3 }

Pattern 2 — Parallel subagents

- parallel:
    - { agent: security-auditor }
    - { agent: docs-writer }
    - { agent: test-writer }

Pattern 3 — Human-in-the-loop

- type: approval
  message: "Approve deploy to prod?"
  approvers: ["@milind", "@vamsi"]

Pattern 4 — Budget guardrail

limits: { max_cost_usd: 2.00 }
on_exceed: pause

Pattern 5 — Observability

"observability": {
  "trace": true,
  "metrics_endpoint": "https://otel.corp/v1/traces",
  "log_level": "info"
}

Best Practices ✅

Decompose big goals into ≤ 7 steps.
Add a critic to every risky step.
Persist memory for multi-session work.
Set budgets (tokens, $, time).
Human gates before destructive actions.
Observe everything (traces, metrics, logs).
Idempotent steps — safe to retry.

Anti-Patterns ❌

One giant prompt that "does everything".
No critics — blind trust in LLM output.
No budget caps — runaway costs.
Skipping human gates on prod actions.
Tightly coupled steps — hard to debug.
No retries / error handling.

Troubleshooting

Symptom	Cause	Fix
Workflow loops forever	No retry cap	Set `max:` on `goto`
Steps run out of order	Missing `depends_on`	Add explicit deps
Critic always passes	Rule too lax	Tighten rule + test
Costs spike	No budget	Add `limits` block
Hard to debug	No tracing	Enable OpenTelemetry
Race conditions	Shared mutable memory	Use scoped memory per step

Starter Template

goal: "<one line>"
limits: { max_cost_usd: 2.00, max_runtime_minutes: 15 }
memory: { short_term: in_session }
steps:
  - { id: plan,    agent: planner }
  - { id: act,     agent: claude-code, depends_on: [plan] }
  - { id: review,  agent: code-reviewer, depends_on: [act] }
  - { id: gate,    type: approval, depends_on: [review] }
  - { id: ship,    type: merge_pr, depends_on: [gate] }

💡 Tip: Start with a 3-step linear workflow. Add parallelism only when you measure a bottleneck.

Glossary

Agentic workflow — A multi-step process orchestrating agents, tools, and humans.
Planner / Executor / Critic — The three core roles.
ReAct — Reason + Act loop pattern.
Human gate — Manual approval step.
Memory — Short-term (session) and long-term (vector store) context.
Kill-switch — A flag that halts all running workflows.

TL;DR​

Why this matters​

The Big Picture​

Core Roles​

Workflow Patterns​

1. Sequential pipeline​

2. Parallel fan-out​

3. Router (pick the right agent)​

4. Reflect-and-retry​

5. Plan-and-act (ReAct)​

Step-by-Step Setup​

1. Define the goal in plain English​

2. Decompose into a plan (plan.yml)​

3. Wire memory​

4. Add critics / validators​

5. Run & observe​

Variants for Different Team Settings​

👤 Solo​

👥 Small team​

🏢 Enterprise​

🌍 Open-source​

Anatomy of a Single Step​

Common Patterns & Recipes​

Pattern 1 — Self-check loop​

Pattern 2 — Parallel subagents​

Pattern 3 — Human-in-the-loop​

Pattern 4 — Budget guardrail​

Pattern 5 — Observability​

Best Practices ✅​

Anti-Patterns ❌​

Troubleshooting​

Starter Template​

Glossary​

Further Reading​