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
| Folder | Holds |
|---|---|
src/ai/mcps/*.json | MCP servers (see MCP Schema Reference) |
src/ai/builtins/*.json | AI 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" }
}
]
}
| Field | Required | Description |
|---|---|---|
name | Yes | snake_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. |
label | Yes | What a person calls it in AI Studio. Never sent to the model. |
kind | Yes | display or ask. See Kinds. |
description | Yes | The tool's declaration, as the model reads it: what it does, when to use it and what it answers with. |
summary | Yes | One line, up to 120 characters: all the model is told until it loads the built-in. |
component | Yes | The key the frontend registers the React component under. |
inputSchema | Yes | What the model sends. An object in the schema subset. |
answerSchema | For ask only | What the person answers, in the schema subset. Refused on a display built-in. |
samples | Yes, at least one | Each 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
displaydraws the component from the call's input and the turn carries on.askdraws 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.
| Type | Keywords besides type, description and default |
|---|---|
object | properties, required, additionalProperties (only false) |
array | items (required, one schema), minItems, maxItems |
string | enum, minLength, maxLength, format (date, date-time, uri or email) |
number | enum, minimum, maximum |
integer | minimum, maximum |
boolean | none |
- Every node has one
type; a type list (["string", "null"]) is refused. - Objects and arrays nest, including arrays of objects.
requirednames only declared properties.defaultis a value of the node's type and, on a node with anenum, one of its values.- Anything else is refused, at the path of the offending keyword:
oneOf,anyOf,allOf,not,$ref,const,pattern,patternProperties,additionalPropertiesother thanfalse, or a keyword on a type it does not apply to (minLengthon 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/*.jsonas an MCP config; - every
src/ai/builtins/*.jsonagainst the format above, with the path of each problem, for exampleBuilt-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 withModule '<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.