Learning Tactus

The Agent Loop

Most useful agents aren’t single-shot. They plan, act, check results, and sometimes need more turns. This chapter teaches multi-turn patterns without turning your code into a brittle “agent script.”

In the last chapter, we made our workflow safe to integrate with the outside world: state, stages, and idempotency guards mean “retry” doesn’t imply “double-send.” Now we’ll address the other reason real workflows need multiple turns: quality.

The goal is not “make the model try again until it looks good.” The goal is:

When You Need a Loop (and When You Don’t)

You need a loop when:

You don’t need a loop when:

In Part II, we’ll use a loop for a very common reason: the first draft is often not the final draft.

The Safe Loop Shape

The safe loop has three properties:

  1. A hard cap (max_turns, max_attempts)
  2. An explicit success condition (“we’re done when X is true”)
  3. A deterministic exit (either success or a clear failure)

In Lua, that usually looks like:

Source: code/chapter-09/00-loop-shapes.tac

local max_attempts = 3
local attempt = 0

while attempt < max_attempts do
  attempt = attempt + 1

  -- take a turn (agent call, tool call, etc.)

  if success then
    break
  end
end

assert(success, "Failed to produce an acceptable result after " .. max_attempts .. " attempts")

Agent-level retry (built-in)

There’s another kind of retry that’s worth separating from your procedure loop: retrying a single agent turn.

Use agent-level retry for:

Configure it directly on the agent:

worker = Agent {
  name = "worker",
  model = "openai/gpt-4o-mini",
  system_prompt = "...",
  retry = {
    enabled = true,
    attempts = 3,
    delay_seconds = 0.5,
    backoff = "exponential",
    on = "infra_plus_validation",
  },
}

This retry policy is bounded (attempts) and local to that call site: it retries the agent’s turn and rolls back the agent’s message history to the start of the attempted turn on each retry.

Three Retry Layers

By this point, Tactus gives you three different places where "retry" can happen:

  1. Standard-library retries Helpers like classification/extraction may expose max_retries because they own a tight prompt + validation loop internally.
  2. Agent-level retries retry = { ... } on Agent { ... } retries one agent turn when the provider fails or the structured output is invalid.
  3. Procedure-level loops Your Lua code decides the workflow needs another step because a check failed, a human rejected the draft, or more information is needed.

The distinction matters:

Make Replays Legible With Logs

Durable execution is only useful if you can understand what happened. Log the shape of your loop:

Use Log.info, Log.warn, and Log.error with structured metadata so traces stay readable.

Per-Turn Tool Control (Preview)

When you call an agent, you can override which tools are available for that call:

Source: code/chapter-09/40-meeting-recap-quality-loop.tac

worker({tools = {}})              -- no tools this turn
worker({tools = {search, done}})  -- only these tools

This is one of the simplest ways to prevent “tool drift”: you only enable tools when the workflow is ready for them.

We’ll use this in the next chapter when we add human approval gates.

Example: Iterate Until the Draft Passes Checks

The example for this chapter is code/chapter-09/40-meeting-recap-quality-loop.tac.

It runs the recap agent, then applies a few deterministic checks like:

If a check fails, the procedure gives the agent targeted feedback and tries again—up to a max attempt count.

Run it:

tactus run code/chapter-09/40-meeting-recap-quality-loop.tac \
  --param recipient_name="Sam" \
  --param raw_notes="Discussed Q1 launch timeline. Risks: vendor delays. Action: Sam to confirm dates by Friday."

And test it in mock mode:

tactus test code/chapter-09/40-meeting-recap-quality-loop.tac --mock

Common Failure Modes (and Fixes)

Looking Ahead

We can now iterate safely and deterministically. The last missing piece for a trustworthy workflow is human-in-the-loop: approvals, reviews, and input requests as durable checkpoints.