---
name: Run an agent with a state machine
description: >-
  Teach an edge engineer a deterministic on-device orchestrator using
  Dynamic Profiles, one active Profile at a time, and no LangChain.
  iOS 27 and macOS 27 only.
---
# Run an agent with a state machine

Use this course to own the agent loop. App state is the source of truth. Dynamic Profiles declare the active persona. Tools request transitions. Your code accepts or rejects them.

## End-to-end agent recipe

1. Start with [lesson 01](01-why-a-state-machine.llms.md) to reject hidden graphs.
2. Use [lesson 02](02-one-active-profile.llms.md) for one active Profile.
3. Use [lesson 03](03-tools-as-transitions.llms.md) so tools propose named state changes.
4. Use [lesson 04](04-build-the-orchestrator.llms.md) to build the loop.
5. Use [lesson 05](05-debug-and-ship.llms.md) to log, cap steps, and ship.
6. Use human HTML for reading and `.llms.md` files for agent execution.

## Constraints

- iOS 27 and macOS 27 only.
- Teach in Swift with Dynamic Profiles, LanguageModelSession, and Tool. Do not use Python for the loop.
- No LangChain, LangGraph, or equivalent hidden runtime.
- One active Dynamic Profile at a time.
- No Mermaid. No em dashes.
- Cite [WWDC26 241](https://developer.apple.com/videos/play/wwdc2026/241/) and [WWDC26 242](https://developer.apple.com/videos/play/wwdc2026/242/) lightly.

## Key concepts

- Own the agent loop with a state machine and Dynamic Profiles.
- App state is the source of truth. One active Profile at a time.
- Tools propose transitions. Your code accepts or rejects them.
- No LangChain or hidden runtime on iOS 27 and macOS 27.

## Takeaways

- You can run an agent with named states, legal moves, and a step cap.
- Product can name the next step. Support can read the log.
- You can bind each state to one Profile with its own instructions, tools, and model.

## Acceptance checks

- Every human lesson HTML has **Key concepts** and **Takeaways** sections before lesson-nav. The course home has the same two headings for the whole course.
- Five lessons and five briefs exist.
- State machine is owned by app code.
- Course index lists SKILL.md and all briefs.

## Environment setup

Xcode 27. Foundation Models. Optional Core AI if a state uses CoreAILanguageModel.