Skip to main content

AI Built-in Schema Reference

An AI built-in is a tool an AI Studio agent can call that draws a component in the chat. An instance or a module declares one per file, in src/ai/builtins/<name>.json, beside its MCPs in src/ai/mcps/.

Core reads, validates and serves the files. The frontend draws them: it registers a React component under the built-in's component key.

Where the files live​

FolderHolds
src/ai/mcps/*.jsonMCP servers (see MCP Schema Reference)
src/ai/builtins/*.jsonAI built-ins (this page)

src/mcps/ is no longer read. stack9-validators refuses a project that still has it: move the files to src/ai/mcps/.

Core reads the instance's folder first (src/ai/builtins in development, the built dist/ai/builtins otherwise), then each installed module's ai/builtins. Files are read on every call, so an edited file shows up without a restart. If the instance and a module declare the same name, the instance's file is used; stack9-validators refuses the clash.

The instance build copies src/ai to dist/ai with the other config folders.

File format​

{
"name": "confirm_choice",
"label": "Confirm a choice",
"kind": "ask",
"description": "Asks the person to pick one of a few options before you carry on. Answers with the option they picked.",
"summary": "Ask the person to pick one of a few options.",
"component": "confirm_choice",
"inputSchema": {
"type": "object",
"properties": {
"question": { "type": "string", "minLength": 1 },
"options": {
"type": "array",
"minItems": 2,
"items": { "type": "string" }
}
},
"required": ["question", "options"],
"additionalProperties": false
},
"answerSchema": {
"type": "object",
"properties": { "choice": { "type": "string" } },
"required": ["choice"]
},
"samples": [
{
"label": "Pick a delivery date",
"input": {
"question": "Which day suits you?",
"options": ["Monday", "Wednesday"]
},
"answer": { "choice": "Wednesday" }
}
]
}
FieldRequiredDescription
nameYessnake_case, starting with a letter, up to 64 characters. Matches the filename. Unique across the instance and its modules. The AI module also refuses a name it reserves for its own built-ins.
labelYesWhat a person calls it in AI Studio. Never sent to the model.
kindYesdisplay or ask. See Kinds.
descriptionYesThe tool's declaration, as the model reads it: what it does, when to use it and what it answers with.
summaryYesOne line, up to 120 characters: all the model is told until it loads the built-in.
componentYesThe key the frontend registers the React component under.
inputSchemaYesWhat the model sends. An object in the schema subset.
answerSchemaFor ask onlyWhat the person answers, in the schema subset. Refused on a display built-in.
samplesYes, at least oneEach has a label and an input, and an answer for ask (no answer for display). AI Studio uses them for previews. Each is checked against the schemas.

No other key is accepted.

Kinds​

  • display draws the component from the call's input and the turn carries on.
  • ask draws the component and waits for the person's answer, which arrives on the next turn.

There is no code kind. A built-in is config, and config cannot run in the agent runtime. To run code, expose it through an MCP.

JSON Schema subset​

inputSchema and answerSchema use a subset of JSON Schema that converts to Zod deterministically and that Bedrock tool schemas accept. The SDK exports it as data, AI_JSON_SCHEMA_SUBSET, which the validator and the Zod generator both read.

TypeKeywords besides type, description and default
objectproperties, required, additionalProperties (only false)
arrayitems (required, one schema), minItems, maxItems
stringenum, minLength, maxLength, format (date, date-time, uri or email)
numberenum, minimum, maximum
integerminimum, maximum
booleannone
  • Every node has one type; a type list (["string", "null"]) is refused.
  • Objects and arrays nest, including arrays of objects.
  • required names only declared properties.
  • default is a value of the node's type and, on a node with an enum, one of its values.
  • Anything else is refused, at the path of the offending keyword: oneOf, anyOf, allOf, not, $ref, const, pattern, patternProperties, additionalProperties other than false, or a keyword on a type it does not apply to (minLength on a number).

Validation​

npx stack9-validators (or --ai for this part only) checks src/ai:

  • no src/mcps/ folder ("MCPs moved to src/ai/mcps");
  • every src/ai/mcps/*.json as an MCP config;
  • every src/ai/builtins/*.json against the format above, with the path of each problem, for example Built-in show_card: inputSchema.properties.title.anyOf: 'anyOf' is not in the supported JSON Schema subset;
  • each built-in name declared once across the instance and the modules in stack9.config.json. Every module listed there must resolve: one that is not installed or not built fails validation with Module '<name>' in stack9.config.json cannot be resolved: install or build it first.

At runtime core leaves out a file that fails validation and logs why.

Reading built-ins from a module​

A module reads them through services.aiBuiltins:

const entries = services.aiBuiltins.list();
// [{ source: 'instance', definition: { name: 'confirm_choice', kind: 'ask', ... } }]

const entry = services.aiBuiltins.get('confirm_choice'); // or null

source is instance or the name of the module that ships the file. definition is the parsed, validated file, typed S9AiBuiltinConfig. The SDK also exports the Zod schema, AiBuiltinConfigSchema, and AiBuiltinValidator.