Skip to content

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_input tool.
  • Your host supplies a form for an operation through a role: form operation, 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.

{
"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.

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.

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.

{
"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.

The resume payload maps each question id to its answer:

{
"interruptId": "int_…",
"status": "resolved",
"payload": {
"answers": {
"name": "prod-eu",
"zone_id": { "selected": ["z1"] }
}
}
}
  • A text answer is a string.
  • A choice answer is {selected: [optionIds], custom?}. custom is accepted only with allowCustom, and counts as one more selection. Without multiple, exactly one selection is allowed and it fills one value; with multiple, 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.