Learning Tactus

State Management

Tools make an agent powerful. State makes an agent workflow safe.

In the last chapter, we gave our recap workflow a “send email” tool (stubbed in this repo). The moment a workflow can change the outside world—send a message, write a file, create a ticket—you inherit a new requirement:

Don’t do the dangerous thing twice.

This chapter focuses on practical state for AI engineering:

state vs Local Variables

Tactus gives you transparent durability: your procedure can pause at tool calls and HITL points and resume later without losing its place.

So why use state at all?

Because state is the workflow’s explicit, inspectable memory:

As a rule of thumb:

The State API (What You Actually Write)

State is accessed via a metatable-enabled state variable:

Source: code/chapter-08/00-state-api-examples.tac

-- Set
state.items_processed = 0

-- Get
local n = state.items_processed

-- Check for existence / truthiness
if state.message_id then
  Log.info("Already sent", {message_id = state.message_id})
end

There are also helper functions for common patterns:

Source: code/chapter-08/00-state-api-examples.tac

State.increment("attempts")        -- attempts += 1
State.increment("attempts", 5)     -- attempts += 5
State.append("events", "drafted")  -- append to a list
local snapshot = State.all()       -- dump all state

You’ll mostly use state.* assignment for normal values, and reach for the helpers when you want concise, intention-revealing operations (counters and append-only logs).

The Big Idea: Idempotency Guards

Durability prevents the runtime from repeating checkpointed work during resume. But in production, “do it twice” still happens:

So you still need a simple, explicit guard: record the result of the side effect, and skip if it already happened.

For “send email”, the obvious marker is a message_id:

Source: code/chapter-08/35-meeting-recap-idempotent-send.tac

local function send_once()
    if state.message_id then
        Log.info("Skipping send (already sent)", {message_id = state.message_id})
        return state.message_id
    end

    Stage.set("sending")

    State.increment("send_attempts")
    state.idempotency_key = state.idempotency_key or ("recap:" .. input.recipient_email .. ":" .. (input.raw_notes or ""))

    local result = send_email({
        to = input.recipient_email,
        subject = state.draft_subject,
        body = state.draft_body,
        idempotency_key = state.idempotency_key
    })

    state.message_id = result.message_id
    return state.message_id
end

This is a tiny pattern with huge consequences: it turns “retries are scary” into “retries are normal”.

A Note on True Idempotency

The best idempotency guard is often an idempotency key supported by the external system (Stripe-style): you generate a stable key, store it in state, and pass it to the API so the API guarantees “only one real send”.

This book’s examples use a stubbed send_email, but the workflow shape is the same.

Make Workflows Legible With Stages

State makes workflows correct. Stages make them understandable.

At the top of a file, declare the stages you expect:

Source: code/chapter-08/35-meeting-recap-idempotent-send.tac

Stages({"drafting", "sending", "complete"})

Inside your procedure, set/advance stages as you go:

Source: code/chapter-08/35-meeting-recap-idempotent-send.tac

Stage.set("drafting")
-- create draft...

Stage.set("sending")
-- call send tool (guarded)...

Stage.set("complete")

This pays off in three ways:

Example: A Retry-Safe “Send” Step

The example for this chapter is code/chapter-08/35-meeting-recap-idempotent-send.tac.

It extends the running recap workflow with:

Run it:

tactus run code/chapter-08/35-meeting-recap-idempotent-send.tac \
  --param recipient_name="Sam" \
  --param recipient_email="sam@example.com" \
  --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-08/35-meeting-recap-idempotent-send.tac --mock

Debugging State

State is meant to be looked at. Two practical tricks:

When a workflow is durable, the hardest bugs are usually “what did it think it already did?” State gives you that answer.

Looking Ahead

We now have a workflow that can integrate with the outside world without being terrifying to retry.

Next, we’ll introduce multi-turn agent loops for a different kind of reliability: not “don’t double-send”, but “don’t ship a low-quality draft”.