Forms
A form pauses a run to ask the user structured questions: free text or a choice among options. Forms come from two places:
- The model asks the user through the built-in
request_inputtool. - Your host supplies a form for an operation through a
role: formoperation, before the operation’s approval or execution.
Both reach the client the same way, as an aidy:input interrupt, and both resume with the same
answer payload.
The form
Section titled “The form”{ "prompt": "Create a Kubernetes cluster", "questions": [ { "id": "name", "prompt": "Name", "kind": "text", "required": true, "placeholder": "prod-eu" }, { "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true, "options": [ { "id": "z1", "label": "Beijing A", "recommended": true }, { "id": "z2", "label": "Beijing B", "description": "No H100 capacity" } ] } ]}| Question key | Meaning |
|---|---|
id |
Unique within the form. |
prompt |
The question. |
kind |
text or choice. |
required |
Whether an answer is needed. |
placeholder, default |
Optional. A choice default is an option id, or a list of ids with multiple. |
options |
For choice: {id, label, description?, recommended?}, at least one. |
multiple |
For choice: allow several options. |
allowCustom |
For choice: allow a free-text answer beside the options. |
A form has a prompt and between 1 and 24 questions.
request_input: the model asks
Section titled “request_input: the model asks”The model sees request_input next to your operations and search. Its arguments are a form.
The model uses it when it needs a decision or details from the user, such as which zone to
create a cluster in, instead of guessing. Invalid forms go back to the model as
invalid_arguments.
role: form: the host asks
Section titled “role: form: the host asks”An operation names a form operation with form. Before the call is approved or executed, aidy
sends the call’s current arguments to the form operation, and your host answers with the form
to show:
"/api/clusters": { "post": { "x-aidy": { "name": "create_cluster", "description": "Create a Kubernetes cluster.", "form": "cluster_form" } }},"/api/clusters/form": { "post": { "x-aidy": { "name": "cluster_form", "role": "form" } }}A form operation is a POST with effect read and approval: never. It receives the target
call’s arguments as its body, so it can prefill defaults or offer only the zones the user’s
quota allows. It is never offered to the model.
In a host form, each question id is the dotted path of the argument it fills
(name, zone_id, network.cidr). aidy writes the answers into the call’s arguments and then
continues: resolve, confirmation lookup, approval, execution. A host form failing with an
HTTP error fails the call with http_{status}, and an invalid form fails it with http_502;
nothing runs in either case.
The interrupt
Section titled “The interrupt”{ "id": "int_…", "reason": "aidy:input", "message": "Create a Kubernetes cluster", "toolCallId": "call_…", "responseSchema": { "type": "object", "properties": { "answers": { "…": "…" } } }, "metadata": { "aidy": { "form": { "prompt": "Create a Kubernetes cluster", "questions": ["…"] } } }}responseSchema is derived from the form, so a generic AG-UI client can validate its own
answer.
Answering
Section titled “Answering”The resume payload maps each question id to its answer:
{ "interruptId": "int_…", "status": "resolved", "payload": { "answers": { "name": "prod-eu", "zone_id": { "selected": ["z1"] } } }}- A
textanswer is a string. - A
choiceanswer is{selected: [optionIds], custom?}.customis accepted only withallowCustom, and counts as one more selection. Withoutmultiple, exactly one selection is allowed and it fills one value; withmultiple, the selections fill a list. - Unknown question ids, unknown option ids and missing required answers are errors.
aidy validates the answers against the form before it closes the interrupt. Answers that fail
end the run with RUN_ERROR code invalid_interaction, and the interrupt stays open, so the
user can answer again in a new run. Sending status: "cancelled" closes the form; the call it
belongs to does not run.
@aidy-dev/react renders forms with AidyForm, and @aidy-dev/client builds the payload
with answerForm.
Related
Section titled “Related”- Approvals: the order of form, resolve, lookup and approval.
- AG-UI profile: interrupts and resume.
x-aidyreference