Agent Playbook

Preflight includes a native AI agent designed to act as your Technical Director. It understands USD validation, RealityKit constraints, and visionOS best practices.

See also: MCP Reference

Capabilities

The Agent is integrated via the Agent Communication Protocol (ACP) and has direct access to these tools:

Core Model + Diagnostics

• load_file(path)
  Load a USD/3D file into the active Preflight session by absolute path.

• get_validation_results()
  Returns validation status, health score, and actionable fix IDs.

• get_scene_graph()
  Returns scene hierarchy summary.

• get_model_info()
  Returns metadata (bounds, scale, up-axis, animation summary).

• get_geometry_breakdown(path?, limit?, sort_by?)
  Returns top heavy prims by triangles/vertices.

• get_screenshot()
  Captures viewport screenshot for visual diagnosis.

Selection + Inspection

• select_prim(path)
  Syncs agent focus with inspector selection.

• inspect(domain, mode, path?)
  Domain-specific schema inspection (for example RealityKit extensions).

Fix Planning + Execution

• create_fix_plan(title, description, steps[])
  Creates a fix stepper in UI. Each step requires a valid fix_id.

• preflight_workflow(...)
  Alias for create_fix_plan.

• execute_fix_plan_step()
  Executes current step of active plan.

• execute_fix_plan_all()
  Executes all remaining steps.

• undo_last_fix()
  Revert the most recently applied fix.

• reset_session()
  Reset session state when current session becomes invalid/corrupted.

Scale + Export

• scale_model(target_meters|preset)
  Scale model to desired physical size.

• export_session(output_path)
  Export flattened session file to path.

• export(output_path)
  Alias for export_session.

UI Controls

• list_gui_actions()
  Lists supported GUI actions and aliases.

• gui(action)
  Trigger supported UI actions (for example camera reset/toggle guides).

Recommended Flow

1. load_file(path)
2. get_validation_results()
3. create_fix_plan(...)
4. execute_fix_plan_step() (or execute_fix_plan_all())
5. get_validation_results() again
6. export_session(output_path) when ready

---

Example Prompts

Try asking the Agent:

Diagnostic

“Why does this character look like it’s lying on the floor?” Answer: “This looks like a Z-Up export issue. I can fix the Up-Axis for you.”

Optimization

“Optimize this texture for visionOS.” Answer: “I found a 4K PNG. I recommend converting it to ASTC 4x4. Should I proceed?”

Repair

“My animation isn’t playing.” Answer: “I detect a skeleton path mismatch. The animation targets /root/hips but the skeleton has /Armature/root/hips. I can strip the prefix now.”

---

External Tools

You can also use external agents (like Claude Code or Gemini) via the CLI:

preflight-mcp serve --port 3000

This exposes the same tools to any MCP-compatible client.