The wizard format

A wizard is one JSON document, its definition. The studio exports it as a .wizard file and imports one back. You can write either by hand or with a tool, check it in your editor against its JSON Schema, and check it completely with wizards validate.

The code that defines the format and checks it is also under the MIT licence, so any tool may read and write wizards.

The definition

{
  "$schema": "https://engenty.ai/schema/v1/wizard.json",
  "version": 1,
  "title": "Create an invoice",
  "description": "A finished invoice from a few details.",
  "avatar": "round",
  "lang": "en",
  "steps": [ … ]
}

JSON Schema

Put the address under "$schema", as in the example above. Editors such as VS Code then complete keys and mark mistakes as you type. JSON Schema and validation says what the schema checks and what only wizards validate can.

Title, description and intro

title is required. description may be empty and intro left out. All three are written in the wizard’s language and translated with it. See Languages.

The avatar

avatar names the engenty that stands for the wizard: the one-eyed figure on its pages, in its chat and calls, and in the studio’s and marketplace’s lists. It is one of ten shapes:

round (the default), drop, dome, flame, oval, bean, pebble, sprout, tower and wedge.

The list is fixed. Any other value is an error in the JSON Schema and in wizards validate, and a wizard cannot bring a picture of its own. Each shape has its own colour.

costume dresses the avatar up for Halloween: witch, devil, bat or pumpkin. Leave it out and the avatar wears none.

Every shape is in assets/engenty/ as a 512 × 512 PNG on a transparent ground. Seven of them also come wearing Goose’s flight helmet. The figures are under CC BY 4.0: you may use, change and share them, commercially too, with credit:

engenty figures © Thru The Heart Creative GmbH - Matthias Platzer, CC BY 4.0, engenty.ai

Using a figure or the name engenty as your own brand, logo or mascot needs permission. See TRADEMARKS.md.

Themes

themes names the looks the wizard offers, in order: ids of the space’s themes, or the built-in brand, host and default. Without it the wizard wears its space’s brand. A theme holds colours, fonts, shape and effects, values only. See Themes.

Languages

A definition is written in one language, and lang names it. Any real language works: en, de, it, fr and so on. It sets the runner’s own words and how numbers and dates are written. The schema checks the shape of the code. wizards validate and the studio check that it names a real language. Without lang, the language is read from the wizard’s own words, and English is the default where they are not clearly German.

People who read another language can read the wizard in theirs. The runner offers their language, from the browser or the time zone, and translates the wizard on request. AI steps then write in that language too. The translation is kept with the wizard in the space, not in the definition. These are never translated:

• ids, branches and their ask statements
• the instructions of AI steps and {{…}} placeholders
• the values of choices: a choice shows a translated label and keeps its value

In the studio, Share → Settings has “Offer a translation”. It turns translation on or off for the wizard, and each language can be edited line by line there.

Version

version is the version of the format the definition is written in, not of the wizard. It is 1 today, and 1 is the default when it is left out.

It changes only with a breaking change to the format. The schemas of each version stay online in their own folder (/schema/v1/, /schema/v2/, …). An app reads only the versions it knows: it refuses a wizard of a newer version instead of running it the wrong way.

The versions of a wizard itself, its drafts and what is published, are kept in the studio, not in the definition.

Steps

Every step has an id, a title, an optional description and an optional next. Ids are letters, digits and _, start with a letter and are unique in the wizard. The last step is always a result step.

Steps run from top to bottom unless a step’s next sends the run elsewhere. See Branches and loops. Steps read what came before through templates such as {{topic}} and {{steps.post}}. See Templates.

A complete wizard

{
  "version": 1,
  "title": "X post with an image",
  "description": "Turns a topic into a finished post with an image.",
  "avatar": "flame",
  "lang": "en",
  "steps": [
    {
      "id": "about", "type": "page", "title": "What is it about?",
      "fields": [
        { "id": "topic", "label": "Topic or occasion", "kind": "textarea", "required": true },
        { "id": "tone", "label": "Tone", "kind": "select",
          "options": ["Casual", "Professional", "Funny"], "default": "Casual" }
      ]
    },
    {
      "id": "post", "type": "agent", "title": "Write the post", "model": "standard",
      "instructions": "Write a post for X on {{topic}}. Tone: {{tone}}. At most 270 characters.",
      "tools": [], "output": { "format": "text" }
    },
    {
      "id": "visual", "type": "generate", "title": "Draw the image", "asset": "image",
      "prompt": "A striking image for this post: {{steps.post}}. No text in the image.",
      "options": { "aspectRatio": "16:9" }
    },
    {
      "id": "check", "type": "review", "title": "Does this work?",
      "show": ["post", "visual"], "edit": true, "regenerate": true
    },
    {
      "id": "done", "type": "result", "title": "Ready to post",
      "deliverables": [
        { "from": "post", "label": "Post", "formats": ["txt", "md"] },
        { "from": "visual", "label": "Image", "formats": ["png"] }
      ]
    }
  ]
}

The studio’s MCP tool get_authoring_guide gives an AI client the same format with its rules for good wizards.

Files and checks

• The .wizard file: what the zip holds and what the import takes.
• JSON Schema and validation: the JSON Schema for your editor and wizards validate.