# 7. ML-Agents Pitfalls and Classroom Use
Part of [[ML-Agents and Inference Engine]]. Prev: [[6. Sentis Directly for Any ONNX Model]].
## 7.1 Pitfalls
| Symptom | Likely cause | Fix |
|---|---|---|
| `mlagents-learn` exports fail or models won't import | PyTorch 2.9+ (ONNX export changes) | reinstall torch within 2.1.1-2.8.0 *before* mlagents (part 2) |
| Trainer starts, Unity never connects | Behavior Type is Inference/Heuristic Only, or an old trainer is still bound to the port | set Default; close stray Python processes |
| "Observation size mismatch" warnings | Space Size doesn't equal the number of floats you add | count every `AddObservation` (a `Vector3` is 3) |
| Model works in Editor, not in a fresh project | different `com.unity.ml-agents` / Sentis versions | pin versions in `Packages/manifest.json`; commit `packages-lock.json` |
| Agent spins in place forever | shaping reward is farmable | use distance deltas or sparse rewards only (part 3.5) |
| Agent jumps into the pit immediately | time penalty bigger than the hazard penalty | cap total time penalty at -1 |
| Reward flat near -1 for 300k steps | task too hard to stumble on | curriculum (part 4.5), bigger coin trigger, spawn the coin closer at first |
| Agents in duplicated areas interfere | world-space positions in observations or resets | everything local to the area root |
| Behaviour differs each run | sampling plus physics | Deterministic Inference on; fixed seeds for the demo; physics is still not bit-exact across machines |
| Memory grows in a Sentis scene | tensors from `ReadbackAndClone*` never disposed, or a new input tensor per frame | `using` on clones, reuse inputs with `Upload`, dispose workers in `OnDestroy` |
| GPU backend slower than CPU | tiny model, readback dominates | `BackendType.CPU` / Burst (part 5.1) |
| Old tutorials use `Unity.Sentis` or `Unity.Barracuda` namespaces | renamed packages | `using Unity.InferenceEngine;` for current Sentis |
## 7.2 Playtest bots (the most useful classroom application)
A trained runner is a free, tireless tester:
1. Train the coin-runner on a gray-boxed level ([[ProBuilder Gray-Boxing and Landmarks]]) with the goal at the exit.
2. Log each episode's death positions and time-to-goal with `PlaytestTelemetry.Log(...)` and the `TelemetryEventHooks` death/checkpoint reports from [[Playtest Telemetry and Heatmaps]].
3. Read the heatmap: jumps it never makes are often jumps players miss too. Rogers' level-design chapter (Level 9 in [[Level Up! (Review)]]) is about exactly this kind of iteration.
Caveat: an agent explores very differently from a human (no fear, perfect reaction time). Treat it as a reachability check, not a fun meter.
## 7.3 A two-week lab plan
| Session | Activity |
|---|---|
| 1 | Install (part 2), run a sample from the repo, watch TensorBoard |
| 2 | Build the coin-runner, play it by heuristic, discuss reward design |
| 3 | Train; each group changes ONE reward term and compares curves |
| 4 | Ship it: Inference Only, difficulty brains (part 5), build |
| 5 | Sentis rune classifier (part 6); design discussion on unreliable controls |
| 6 | Critique: where would authored AI ([[Enemy AI State Machine]], [[Unity Behavior]]) have been better? |
Assessment idea: students submit their YAML, a TensorBoard screenshot, and a one-paragraph explanation of a reward hack they observed.
## 7.4 Ethics and data notes for class
- Models downloaded from the internet carry licences and biases; check the model card before using it in student work.
- Training on lab PCs can run for hours; agree a policy on GPU use and power.
## Sources
- https://docs.unity3d.com/Packages/
[email protected]/manual/Installation.html
- https://docs.unity3d.com/Packages/
[email protected]/manual/index.html
- https://docs.unity3d.com/Packages/
[email protected]/manual/index.html