Human Approval & Applied Single-Agent Builds: overview

Real agents take actions, and this module puts a preview and a person between an agent's decision and its effect. It then builds applied single agents: two research agents and a financial analyst over live data, a text-to-SQL workflow and agent, and fixed workflow apps over business text. The T8.3 notebooks build on four ideas: dry runs, approval gates, text-to-SQL and workflow apps.

The running example is the Larkspur Cloud handbook from T5.1 to T5.3, seen from the operations side. After the eu-west outage an agent drafts posts for the Larkspur status feed, and a person approves each one before it goes out. The research and analyst builds keep their notebooks' live sources (the web, weather, market data), and the text-to-SQL lesson keeps the notebooks' comic-store database, because its numbers come from that data. The interview questions move the same ideas to Larkspur's billing data and support queue.

• A dry run calls the action's own code path in preview mode and returns the effect without applying it, so the reviewer judges what will happen instead of a description of it.
• An approval gate pauses the graph with interrupt(), keeps the run in a checkpointer and resumes it with the reviewer's decision. It fails closed (only the exact word approve approves), and the approval covers a fingerprint of the preview. Editing "72 hours" to "48 hours" after review changes it from c4e9e330698e to 11673ae3c1d4, and the publish node refuses.
• Agents over live data need budgets on tool output (three pages of 4,000 characters per search), arithmetic done in code (14 summary fields in place of about 250 daily prices) and checks against the tool data from the same run, because there is no fixed expected answer.
• Text-to-SQL retrieves by computing over every row, which vectors cannot do for counts, sums and rankings. In the notebooks' database, 16 of the 20 sales disagree with their own line items, so the top salesperson is John Doe by one definition of revenue and Alice Brown by the other. A business rule in the prompt has to decide.
• A workflow app keeps the LLM to fixed steps with structured output, and does the routing, checking and rendering in code. The workflow form of text-to-SQL costs 2 LLM calls per question, and one structured call per support ticket makes a quarter of the calls of a four-step chain.

The graph stops at Review and waits, for seconds or for hours, while the checkpointer holds its state. Two checks guard the live call. The first is the reviewer's answer, and anything unclear counts as no. The second is a hash comparison at publish time, which catches any change between what the reviewer saw and what is about to run.

The approval gate: open the file in a browser. Keep the eu-west post and try the answers ␣Approve␣, approved and sure, why not: the first publishes, the other two fail closed. Then set the answer back to approve and pick Small edit: the reviewer said yes, the audit log records an approve, and the post still does not publish. Last, approve the uptime post. It reaches the feed, because the gate enforces whatever the reviewer decides.

• Before: T4.4 teaches interrupt() and checkpointers. T7.1 gives the tool schemas and the rule that tool failures come back as messages, which every build here follows. T7.2 supplies create_agent, structured output and HumanInTheLoopMiddleware, which is built on the same pause. T7.3's chaining, routing and parallel patterns are the parts the workflow apps assemble. T6.4 builds RAG over CSV and JSON rows, the vector side of this module's SQL-or-vectors lab, and T5.1 shows why top-k retrieval cannot aggregate.
• Next: T9.1 to T9.3 grade, correct and route retrieval. Sending a question to SQL or to the vector index is T9.3's routing problem. T9.4 exposes retrieval as an agent tool behind the same approval gates.

• Split every consequential action into a dry run and a live call that share one code path, and keep the dry run in its own node before the pause.
• Fail closed. Only an explicit approve approves, and the approval covers the fingerprint of what was previewed, recomputed at execute time.
• Give agents over live data budgeted tools and do their arithmetic in code, then check every number and source against the tool data from the same run.
• Use SQL to retrieve when the answer is a count, sum or ranking over rows, open it read-only, and write ambiguous business terms down as rules. Let the LLM fill typed fields and keep routing, checks and the final document in code.