表单
表单会暂停运行,向用户提出结构化的问题:自由文本,或在若干选项中选择。表单有两个来源:
- 模型通过内置的
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 个问题。
request_input:模型提问
Section titled “request_input:模型提问”模型在你的操作和 search 旁边还能看到 request_input,它的参数就是一个表单。当模型需要用户做决定或补充细节(比如在哪个可用区创建集群)时,会用它来问,而不是自己猜。不合法的表单以 invalid_arguments 返回给模型。
role: form:宿主提问
Section titled “role: form:宿主提问”操作用 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。
- 审批:表单、resolve、查询和审批的先后顺序。
- AG-UI profile:中断与恢复。
x-aidy参考