Project 8: Audit-Ready State Machine Agent

Quick Reference

Attribute Value
Difficulty 5
Time 3-4 weeks
Main Stack jido (FSM strategy) + req_llm for narrative reporting
Alternatives Pure script orchestration + ad-hoc logs
Why Now Production workloads need both correctness and auditability

What You Will Build

A finite-state agent that handles request lifecycle (draft → approved → executed → completed), emits state transition evidence, and produces audit-friendly human summaries using LLM assistance.

Real World Outcome

$ mix run -e "AuditAgentDemo.handoff(:incident_case_14)"
[info] case=incident_case_14 from=draft to=approved by=policy_agent
[info] transition=approved evidence_saved digest=ea93...
[info] transition=executed output=runbook_steps emitted=state_changed,notify
[info] transition=completed checksum=7c51...

You should end with:

  • immutable state transition log
  • structured execution evidence
  • one final audit bundle with timeline and cost summary

The Core Question You Are Answering

“How do you build stateful agents that are both autonomous and legally explainable?”

Why This Project Matters

Jido supports FSM-based strategy execution. For regulated or operationally sensitive workflows, FSM adds deterministic transitions and auditable checkpoints to otherwise opaque agent behavior.

Architecture

Input Request
     |
     v
+-----------------------+
| FSM Agent State      |
| States: draft,       |
| review, execute, close |
+----------+------------+
           |
   +-------+-------+
   |              |
   v              v
Action Module  Directive Engine
(Approve/Reject) (Emit, Schedule, Stop)
   |              |
   +------+-------+
          |
          v
 +-----------------------+
 | Transition Log        |
 | - old_state/new_state |
 | - signal_id           |
 | - timestamp           |
 | - actor               |
 +-----------+-----------+
             |
             v
    +-------------------+
    | Audit Artifact    |
    | + timeline       |
    | + evidence hash  |
    | + cost breakdown |
    +-------------------+

Deep Dive Steps

1. State Design

Define allowed transitions and illegal transitions explicitly:

  • draft -> review
  • review -> approved/rejected
  • approved -> executing
  • executing -> completed/failed
  • failed -> review or terminated

2. Guard Functions

Guards prevent invalid transitions:

  • missing approvals
  • missing evidence
  • failed prerequisite signals

3. Transition Logging

Every state change records:

  • previous state
  • new state
  • reason code
  • correlation identifiers

4. Agent-side Error Signals

Map:

  • business exceptions to Stop
  • transient failures to Schedule
  • completion to StopChild/Emit depending on topology

5. LLM-Supported Explanation Step

At transition boundaries, optionally call req_llm to generate concise explanations from immutable traces (human review text only, not control).

Concepts You Must Understand First

  1. FSM semantics
    • Why not every state transition is valid.
  2. Audit evidence
    • What makes an event admissible as proof.
  3. Directive lifecycle
    • How stop/schedule/spawn directives affect process lifecycle.

Questions to Guide Your Design

  1. State invariants
    • Which invariants must hold in each state?
  2. Evidence
    • What minimum payload guarantees replayability?
  3. Recovery
    • How do you rehydrate state from transition logs?

Thinking Exercise

Create a trace for a failed workflow:

  • draft -> review -> approved -> executing -> failed

For each transition, specify:

  • required guard
  • logged evidence
  • operator recovery command

Interview Questions They Will Ask

  1. “When would you use FSM strategy over direct action strategy?”
  2. “How do you prove a transition was legal at runtime?”
  3. “What is stored for audit and what is not?”
  4. “How do you avoid log tampering?”
  5. “Where should LLM summarization fit in regulated workflows?”

Hints in Layers

Hint 1: Start by drawing the finite-state graph Before implementing code, enumerate every state and arrow.

Hint 2: Persist every transition No transition should be implicit.

Hint 3: Make failure states explicit failed and terminated must be first-class.

Hint 4: Use deterministic explanation step Only summarize from transition log, never raw prompt context.

Common Pitfalls and Debugging

  • Problem: Transition loops due to missing terminal branch.
    • Why: fallback transition points to non-terminal state.
    • Fix: explicit exhaustiveness checks in guards.
    • Quick test: assert :error on any unknown transition.
  • Problem: Audit record drift from runtime state.
    • Why: side effects before logging.
    • Fix: log before directive execution.
    • Quick test: inject failing execute directive and verify pre-state log exists.
  • Problem: LLM summary differs from authoritative logs.
    • Why: summary uses live context outside trace.
    • Fix: summary generator reads only signed transition records.
    • Quick test: compare summary hash across replay.

Books That Will Help

Topic Book Chapter
Finite state machines Designing Event-Driven Systems State transitions and consistency
Systems reliability Release It! Designing robust failure states

Definition of Done

  • All legal transitions defined and invalid transitions rejected
  • transition log is immutable and queryable
  • audit bundle includes cost, actor, state lineage
  • failed cases remain recoverable
  • deterministic summaries are generated from logged evidence

References

  • https://hexdocs.pm/jido/2.0.0-rc.4/readme.html
  • https://hexdocs.pm/jido/2.0.0-rc.4/readme.html#Core%20Concepts