Deepagents vs deterministic spine: keep harness thin, tools fat
HackPrinceton Pinpoint (CoStar track): photo→indoor location→responder packet with CoStar + Matterport + Vexcel.
**What worked**
- Use deepagents ONLY for the harness: create_deep_agent(subagents=[...dicts...], interrupt_on=..., checkpointer=MemorySaver(), middleware=[TodoListMiddleware()]).
- Put the actual work in plain Python tools (routing Dijkstra, belief/info-gain localization, stubs, Vexcel fetch). Pass those callables as subagent tools.
- Keep a deterministic orchestrator.py as the default demo path (ThreadPoolExecutor + as_completed). Same tool layer; --real-llm swaps to deepagents.
- Dict subagents are SYNC and block the supervisor. True parallel async needs AsyncSubAgent + Agent Protocol/Agent Server — overkill for a local hackathon. Prompting "run in parallel" on sync subagents is a lie; do parallel in the stub orchestrator.
- Split bloated files: agent_spec.py (Commander prompt + 5 subagent dicts), pipeline.py (records/locator/site/router/verifier steps), gates.py (HITL), failures.py (UNABLE/DEGRADED). deepagents owns *when*; pipeline owns *what*.
- Skip caller questions when best_entry_under_belief says all top candidates share the same door — real latency win.
- HITL: interrupt_on={"send_packet": {"allowed_decisions": ["approve","reject"]}} + Command(resume=...). Mirror the same gates in the stub path.
- Fixture cache: lru_cache + deepcopy so belief mutation does not poison the cache.
- Vexcel ortho/extract at 1200 Smith St (Houston) returned a real 640x640 JPEG (~166KB) with property/extract features; fall back to fixtures on VexcelUnavailable.
**Gotchas**
- deepagents needs Python 3.11+; sandbox 3.10 will ImportError — fall back to orchestrator.
- Do not reimplement skip-question Dijkstra; reuse question_worth_asking from best_entry_under_belief on the above-threshold candidate set.
- Drain parallel futures with as_completed, not submit-order .result(), or packet streaming waits on the wrong prefix.
- Keep building_id/fixture hardcodes out of step logic early or the second building breaks everything.
**Readable layout that clarified deepagents usage** agent_spec → deep_agent (library) | orchestrator → pipeline (no library) | stubs/routing/localization/vexcel (tools both paths share).