Agent Workflows

Overview

Ad-hoc prompting gets you started with AI agents, but it does not scale. When a task involves multiple steps -- reviewing code across dimensions, migrating files to a new pattern, generating tests for an entire module -- you need something structured. Agent workflows are repeatable, multi-step orchestrations that chain agent invocations together with deterministic logic. This lesson covers why workflows matter, the patterns that make them effective, and how to build them as executable scripts.

Why Workflows Beat Ad-Hoc Prompting

Consider a developer who asks an agent to "review this PR." The agent might focus on style one time and security the next. It might miss performance issues entirely. There is no consistency, no guarantee of coverage, and no way to compare results across runs.

Now consider the same task defined as a workflow:

1. Read the diff
2. Review for correctness bugs
3. Review for security vulnerabilities
4. Review for performance regressions
5. Synthesize findings into a single review

Each step has a defined scope. The workflow runs the same way every time. Results are auditable. This is the difference between improvisation and orchestration.

Workflows turn agent capabilities into team processes. An ad-hoc prompt is a conversation; a workflow is a procedure.

Workflow Patterns

Three fundamental patterns cover most agent orchestration needs. Knowing which one to apply is the first decision in workflow design.

Three workflow patterns: Sequential Pipeline shows Step 1 flowing to Step 2 then Step 3 in order. Fan-Out/Fan-In shows a Dispatch node splitting to three parallel tasks (A, B, C) that all converge into a Merge step. Iterative Loop shows an Attempt flowing to Validate, which either loops back through Fix on failure or proceeds to Done on success.

Sequential pipeline runs steps in order, where each step's output feeds the next. Use this when steps have dependencies -- for example, "generate types, then generate API client from types, then generate tests for the client."

Fan-out / fan-in dispatches independent tasks in parallel, then merges results. Use this when the same input needs to be analyzed from multiple angles -- like reviewing a PR for bugs, security, and performance simultaneously.

Iterative loop repeats an attempt-validate-fix cycle until a success condition is met. This is the pattern behind test-driven development with agents: write code, run tests, fix failures, repeat.

Anatomy of a Workflow Script

A workflow script is an executable file that orchestrates agent invocations using your CLI tool. It is not a prompt -- it is code. The agent handles the LLM reasoning; the script handles the control flow.

This script uses the fan-out / fan-in pattern. Three reviews run concurrently, then a synthesis step merges them. The developer gets one consolidated report instead of three fragmented ones.

Workflow Execution Flow

Here is how a typical workflow executes from trigger to output:

Workflow execution sequence: the developer triggers the workflow script, which dispatches three agents in parallel — one for correctness review, one for security review, one for performance review. Each agent returns its findings to the workflow script. The script then sends all findings to a synthesis agent, which returns a consolidated review. The workflow script delivers the final review-summary.md to the developer.

Notice how the workflow script acts as an orchestrator -- it decides what runs, when, and in what order. The agents handle the reasoning within each step.

Common Workflow Use Cases

The patterns above apply to a wide range of development tasks. Here are the most impactful ones:

• Multi-dimensional code review -- fan-out reviews for bugs, security, performance, style, then synthesize
• Migration scripts -- sequential pipeline that identifies files to migrate, transforms them one by one, then validates the result
• Test generation -- fan-out to generate unit tests, integration tests, and edge case tests in parallel
• Documentation updates -- iterative loop that generates docs, validates them against the code, and fixes inconsistencies
• Refactoring -- sequential pipeline that analyzes dependencies, plans the refactor, executes it, and runs the test suite

Building a Sequential Pipeline

Here is a sequential workflow for migrating files from one pattern to another:

Each step depends on the previous one. The file list feeds the migration loop, and the test run validates everything at the end.

Designing Effective Prompts for Workflow Steps

The quality of a workflow depends on the quality of each step's prompt. Follow these principles:

• Scope narrowly -- each step should have one job. "Review for security issues" is better than "review this code."
• Provide context -- include the relevant input (diff, file contents, previous step output) directly in the prompt.
• Specify format -- tell the agent what the output should look like. "Output a markdown list of findings with severity labels" produces more usable results than "tell me what you find."
• Set constraints -- tell the agent what not to do. "Do not suggest style changes" keeps a correctness reviewer focused.

Each workflow step should read like a task assignment to a specialist. Vague delegation produces vague results.

When Not to Use Workflows

Workflows add structure, but not every task needs structure. Use ad-hoc prompting when:

• The task is exploratory ("help me understand this module")
• The task is a one-off ("rename this variable across the codebase")
• You are still figuring out the right approach
• The overhead of defining a workflow exceeds the benefit

Use workflows when:

• The task recurs (weekly reviews, release prep, migration batches)
• The task has multiple independent dimensions (multi-reviewer patterns)
• Consistency matters (compliance checks, audit trails)
• The task is delegated to CI (no human in the loop)

Summary

Agent workflows transform ad-hoc agent usage into repeatable, auditable development processes. The three core patterns -- sequential pipeline, fan-out / fan-in, and iterative loop -- cover the vast majority of multi-step agent tasks. Workflows are executable scripts, not prompts. They use the agent CLI in headless mode, chain steps with deterministic logic, and produce consistent results across runs. The key to effective workflows is scoping each step narrowly with specific prompts that include the right context, format expectations, and constraints. In the next lesson, we will embed these workflows into CI/CD pipelines so they run automatically on every push and pull request.