Agents & workflows

• Workflow: a predefined code path with LLM steps inside it. YOU wrote the sequence, the branches, the retries. The model fills in the smart parts; your code decides what happens next. Deterministic shape, predictable cost, testable step by step.
• Agent: the model owns the loop. It sees tool results, decides the next action itself, and keeps going until it judges the task done. Flexible, powerful, and harder to bound - cost, latency and failure modes all become open-ended.

The simplest composition: break a task into a fixed sequence of LLM calls, each consuming the previous output. Classic shape: draft, critique, revise. Between steps you can add a gate - a cheap code check that decides whether the next (expensive) step is even needed.

When do gates between steps pay? When steps are expensive and failures are detectable: a length check, a regex for required sections, a schema validation, or (as here) a cheap critique call. The gate turns "hope the chain worked" into "prove each step worked" - the same instinct as the evals page (6.2).

When inputs fall into distinct categories, don't build one prompt that handles everything - classify the input first, then send it to a specialized prompt (and a right-sized model). Easy tickets go to a cheap fast model with a short prompt; hard ones go to the capable model with the full playbook.

Two wins: each specialist prompt stays short and sharp (no "if it's a refund... but if it's a bug..." spaghetti), and you stop paying frontier-model prices for password resets. The classifier is itself a great eval target - a labeled set of 50 tickets tells you its accuracy in minutes.

Two distinct flavors share the same machinery:

• Sectioning: split independent work, run it concurrently, aggregate. Review 10 documents at once; check a draft for tone, accuracy and legal exposure in three parallel calls.
• Voting: run the SAME task N times, then take the majority answer (or have a judge model pick). Buys reliability on judgment calls where any single call is noisy.

Sectioning is the same gather() with different prompts per task, plus one final aggregation call. Costs scale linearly with N, so vote where mistakes are expensive (moderation, compliance flags) and skip it where they're cheap.

The last two workflow patterns add dynamism while your code still owns the outer structure:

• Orchestrator-workers: when you can't predict the subtasks upfront, let a lead model decompose the task at runtime ("this codebase change touches these 4 files, here's a work order for each"), fan the work orders out to worker calls, then synthesize. Unlike sectioning, the SPLIT itself is model-decided - but your code still runs the fan-out and the merge.
• Evaluator-optimizer: a generate-evaluate-refine loop. One call produces, a second grades against explicit criteria, and the producer retries with the feedback until the grader passes or a retry budget runs out. This is your 6.2 evals discipline turned into a runtime component - the grader IS a model-based eval.

The whole agent loop fits in a dozen lines: call the model with tools, execute whatever tool it asks for, feed the result back, repeat until it stops asking - or until you cut it off.

The key lesson from the official module is environment inspection: a good agent doesn't assume - it looks. It lists the directory before editing, runs the test before claiming the fix, reads the error instead of guessing. Tool results are the agent's senses; design tools so their outputs are informative enough to steer the next step.

Qualities of tasks agents are good at:

• Verifiable progress: there's a signal that says "closer" or "done" - a test suite, a compiler, a schema check. Without it the agent can't tell success from failure and neither can you.
• Recoverable errors: a wrong step can be observed and undone. Editing a file in a git repo: recoverable. Sending an email: not.
• Bounded blast radius: the worst plausible action is affordable. A sandbox, a branch, a staging environment - never the production database on day one.

Guardrails, in order of importance: tool allowlists (the agent literally cannot do what it has no tool for), step budgets (every loop gets a max), and human gates (irreversible actions - deploy, send, delete - pause for approval). Design the guardrails before the prompt, not after the incident.

Map Claude Code onto everything above: it's an agent loop (the model decides which file to read next), with environment inspection (it greps before editing, runs tests after), tool allowlists (your permission settings), step budgets and human gates (approval prompts on risky commands). Three practices from the official module:

• Parallelizing Claude Code: run multiple instances on independent tasks at once - one per git worktree so they can't step on each other's files. One instance fixes a bug on a branch while another writes docs on a second worktree. This is the sectioning pattern, applied to your own workday.
• Automated debugging: point Claude Code at a failing test and let the loop run: run test, read failure, form hypothesis, edit, re-run. The failing test is the "verifiable progress" signal in its purest form - which is exactly why this is the canonical agent demo.
• Enhancing with MCP: every MCP server you add (6.6) is a new sense or limb - a database server means it can inspect real data while debugging, a browser server means it can check the rendered page. The agent loop is fixed; the toolset is where you invest.

How it works: the same agent loop, with the environment swapped for a desktop. Claude receives a screenshot, decides an action (click at coordinates, type text, press keys, scroll), your harness executes it, and a fresh screenshot comes back as the tool result. Look, act, look again - environment inspection at 100% literalness.

• Good for: legacy UI automation (that internal tool with no API), end-to-end testing of real interfaces ("complete checkout as a new user and report anything confusing"), and one-off migrations through GUI-only admin panels.
• Why tight sandboxing is non-negotiable: a screen-driving agent can click ANYTHING visible - real send buttons, real delete confirmations, whatever a malicious page displays (prompt injection now arrives via screenshot). Run it in a dedicated VM or container with a throwaway account, no credentials that matter, network limited to what the task needs, and a human gate before anything irreversible. Slower and costlier than an API path too - so if an API exists, use 6.3 tool use instead.