跳转到内容

表单

表单会暂停运行,向用户提出结构化的问题:自由文本,或在若干选项中选择。表单有两个来源:

  • 模型通过内置的 request_input 工具向用户提问。
  • 宿主通过一个 role: form 操作为某个操作提供表单,在该操作审批或执行之前出现。

两者到达客户端的方式相同,都是 aidy:input 中断,恢复时也使用相同的回答格式。

{
"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" }
]
}
]
}
问题字段 含义
id 在表单内唯一。
prompt 问题文本。
kind text 或 choice。
required 是否必须回答。
placeholder、default 可选。choice 的默认值是选项 id,开启 multiple 时可以是 id 列表。
options 用于 choice:{id, label, description?, recommended?},至少一个。
multiple 用于 choice:允许多选。
allowCustom 用于 choice:除选项外还允许自由填写。

一个表单包含 prompt 和 1 到 24 个问题。

模型在你的操作和 search 旁边还能看到 request_input,它的参数就是一个表单。当模型需要用户做决定或补充细节(比如在哪个可用区创建集群)时,会用它来问,而不是自己猜。不合法的表单以 invalid_arguments 返回给模型。

操作用 form 指定一个表单操作。在调用被审批或执行之前,aidy 把调用当前的参数发给表单操作,宿主返回要展示的表单:

"/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" }
}
}

表单操作是效果为 read、approval: never 的 POST。它以请求体接收目标调用的参数,因此可以预填默认值,或只提供用户配额允许的可用区。它从不提供给模型。

在宿主表单中,每个问题的 id 是它所填参数的点分路径(name、zone_id、network.cidr)。aidy 把回答写进调用参数,然后继续:resolve、confirmation 查询、审批、执行。表单操作返回 HTTP 错误时,调用以 http_{status} 失败;返回的表单不合法时以 http_502 失败。两种情况下都不会执行任何操作。

{
"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 由表单派生,通用的 AG-UI 客户端可以用它自行校验回答。

恢复时的 payload 把每个问题 id 映射到它的回答:

{
"interruptId": "int_…",
"status": "resolved",
"payload": {
"answers": {
"name": "prod-eu",
"zone_id": { "selected": ["z1"] }
}
}
}
  • text 的回答是字符串。
  • choice 的回答是 {selected: [optionIds], custom?}。只有开启 allowCustom 才接受 custom,它算作多一个选择。未开启 multiple 时只允许恰好一个选择,填入单个值;开启后,所有选择填入一个列表。
  • 未知的问题 id、未知的选项 id 以及缺失的必答项都是错误。

aidy 在关闭中断之前按表单校验回答。不合格的回答会让运行以 RUN_ERROR(code 为 invalid_interaction)结束,中断保持打开,用户可以在新的运行中重新回答。发送 status: "cancelled" 会关闭表单,对应的调用不会执行。

@aidy-dev/react 用 AidyForm 渲染表单,@aidy-dev/client 用 answerForm 构造 payload。