---
title: "Why agents need a state machine"
lesson_id: "01"
---

# Why agents need a state machine

- **Lesson ID:** 01
- **Goal:** Own a finite set of named states and reject hidden graph runtimes.
- **Human lesson:** [01-why-a-state-machine.html](01-why-a-state-machine.html)

## Prerequisites

- iOS 27 or macOS 27.

## Inputs, outputs, and artifacts

- **Inputs:** A feature that would otherwise "just tool-call."
- **Outputs:** A four-state sketch: gather, decide, act, review.

## Agent build steps

1. Name finite states and legal exits in a Swift enum and transition table.
2. Forbid LangChain and similar hidden loops.
3. Point at [WWDC26 242](https://developer.apple.com/videos/play/wwdc2026/242/) as Profiles plus app-owned mode.
4. Require that a teammate can predict the next step.

## Constraints

No LangChain. No em dashes.

## Key concepts

- Shipped agents have finite states: gather, decide, act, review, done.
- Each state has a Profile, a tool allow-list, and legal exits.
- Write a `Mode` enum and a legal transition table.
- WWDC26 orchestration patterns still expect you to own mode.

## Takeaways

- Named states make the next step visible.
- Do not import LangChain or LangGraph.
- A teammate should point at current state and say what can happen next.

## Acceptance checks

- States are named.
- Hidden runtimes are rejected.
- Agent brief link is present.