产品动态
产品公告
Widget Action 使用说明
什么是 Action？
Widget 不仅用于信息展示，同时也支持用户的交互行为。
Action 用于描述当用户在 Widget 中完成某项交互操作（例如点击、选择、填写表单）后，系统应执行的具体行为。通过 Action，Widget 能够将用户操作结果及相关数据返回给智能体，触发后续流程。在 Widget 中，onClickAction、onSubmitAction 和 onChangeAction 均属于 Action 类型。
Widget 是否支持交互取决于是否包含支持 Action 配置的组件，您可以通过组件属性的配置声明对应的 Action 的类型及参数。Action 通常包含以下两个核心字段：
字段 | 类型 | 描述 |
type | "sys.chat" | "sys.go_to_url" | "sys.download" | 用于定义用户交互后执行的具体行为类型。 |
payload | object | 提供指定 Action 类型所需的数据内容。 |
注意：
不支持在 Widget 模板（Template）中直接编写 Action 的具体实现逻辑。支持声明 Action 的 type 和 payload，当前仅支持使用官方预置的 Action 类型，暂不支持自定义。
官方预置 Action
ADP 官方提供了三种预置 Action 类型，可直接用于 Widget 交互配置。
sys.chat
定义
type: "sys.chat"
功能说明
sys.chat 用于向智能体发送一条对话消息，当用户在 Widget 中触发该 Action 时，系统会将指定内容作为新的用户输入进入当前对话的上下文，参与后续的推理、判断与流程决策。适用场景
适用于信息收集、补充说明等需要 Agent 感知并继续决策的交互流程。
示例说明
Template 示例：
用户单击重新选择 Button 后，向 Agent 发送“重新选择方案”的对话信息。
<Buttonlabel="重新选择"onClickAction={{type: "sys.chat",payload: { query: "重新选择方案" } }} />
代码说明：
type 指定为
sys.chat，表示触发对话输入。payload 用于提供 Agent 可理解的文本内容，即直接发送的对话消息。
注意：
payload 字段名称支持自定义，可以根据具体场景设置字段名和对应值。
在此示例中，query 是自定义字段，表示用户的操作或选择。
sys.go_to_url
定义
type: "sys.go_to_url"
功能说明
sys.go_to_url 支持触发页面跳转，由前端直接执行。该 Action 不经过模型推理，也不会写入对话上下文。适用场景
适用于跳转到详情页、打开外部链接等不需要智能体感知用户意图或参与决策的操作。
示例说明
用户单击查看详情 Button 后，执行页面跳转到目标网址。
Template 示例：
<Buttonlabel="查看详情"onClickAction={{type: "sys.go_to_url",payload: {url: "https://adp.cloud.tencent.com/" } }}/>
代码说明：
type 为
sys.go_to_url，表示执行页面跳转行为。payload 用于指定目标地址，支持通过变量进行动态配置。
跳转行为由前端直接完成，不影响当前对话与 Agent 状态。
注意：
sys.go_to_url 对应的 payload 必须严格为 url，不支持自定义其他字段。如果您需要传递其他参数，考虑使用
sys.chat 代替。sys.download
定义
type: "sys.download"
功能说明
sys.download 用于触发文件下载行为，当用户在 Widget 中触发该 Action 时，系统会根据配置的 URL 地址发起文件下载。该 Action 不经过模型推理，也不会写入对话上下文。适用场景
适用于向用户提供结果文件下载的场景，例如下载图片、音频、文档等生成内容。
示例说明
用户单击下载图片 Button 后，将下载指定地址对应的文件。
Template 示例：
<Buttonlabel="下载图片"onClickAction={{type: 'sys.download',payload: {url: 'https://cdn.xiaowei.qq.com/static/adp/app-default-avatar.png',},}}style="primary"block/>
代码说明：
type 为
sys.download，表示触发文件下载行为。payload 用于指定待下载文件的资源地址（url）。
下载行为由前端直接完成，不影响当前对话与 Agent 状态。
注意：
sys.download 对应的 payload 中的 url 为必填字段，用于指定下载资源地址，否则无法进行文件下载；filename字段为选填字段，用于自定义下载文件名，若未配置，系统将默认使用 URL 路径中最后一级内容作为文件名。其他类型的 Action 目前暂未支持，后续将支持自定义。
当引用 Widget 时，如果该 Widget 配置了 Action，在 Multi-Agent 模式中，相关配置会自动回显到 Widget 设置和预览页；在工作流画布中，相关配置会自动回显到 Widget 节点详情页。对于平台暂不支持配置的交互操作，操作栏内容将以红色高亮提示。
Multi-Agent 模式正确配置 Action 的回显 | Multi-Agent 模式错误配置 Action 的回显 |
 |  |
Widget 节点详情正确配置 Action 的回显 | Widget 节点详情错误配置 Action 的回显 |
 |  |
Action 的执行流程
完整的 Action 触发流程如下：
1. 用户在 Widget 中执行交互操作：例如点击按钮、提交选择或填写表单。
2. 前端触发 Action 回调：前端根据组件中配置的 Action，将对应的 type 与 payload 发送至系统进行处理。
3. 系统根据 Action 类型执行对应行为：
sys.go_to_url：由前端直接执行页面跳转至指定地址。sys.chat：将 payload 中的内容作为新的对话输入，提交给智能体，继续参与后续推理与流程决策。sys.download：根据 payload 中配置的资源地址进行文件下载。支持 Action 的组件
以下组件支持在配置中声明 Action。
Component | Action 属性 | 说明 |
Button | onClickAction | 点击触发 |
Form | onSubmitAction | 表单提交 |
DatePicker | onChangeAction | 日期变化 |
Select | | 选择变化 |
Checkbox | | 勾选变化 |
RadioGroup | | 单选变化 |
说明：
超链接可直接在 <Markdown> 中使用，无需额外定义 Action：
<Markdown value={"点击 [这里](https://example.com) 查看更多"} />
表单类 Widget 参数提交机制
信息收集类组件
以下组件可以采集用户输入，并在 Action 触发时输出字段：
Input
Textarea
Select
Checkbox
RadioGroup
DatePicker
上述组件需要配置
name字段，用于标识提交参数的字段名。Widget 提交参数
Widget 在 Action 触发后，向后端发送完整的参数集合，包括：
1. Action 中声明的 payload。
2. 表单中所有信息收集组件的用户输入值。
提交规则：
点击 / 选择类 Action（onClickAction）：仅提交 Action 中声明的 payload，不会自动收集表单字段。
表单提交（onSubmitAction）：自动合并表单内所有信息收集组件并以各组件的
name作为字段名提交对应值。Widget 示例
Template 示例：
<Card size="sm"><FormonSubmitAction={{type: 'sys.chat',payload: { result: 'submit' },}}><Col gap={3}><Title value="医院与科室信息收集表" size="sm" /><Col gap={3}><Col gap={2}><Label value="医院名称" /><Input name="hospital" placeholder="请输入医院名称" /></Col><Col gap={2}><Label value="科室" /><Input name="department" placeholder="请输入科室名称" /></Col></Col><Row><Spacer /><Button submit label="确定" style="primary" /><Buttonlabel="取消"variant="outline"onClickAction={{type: 'sys.chat',payload: { query: '取消填写' },}}/></Row></Col></Form></Card>
效果展示如下：
当用户在输入框中填写：
医院名称：北京301医院。
科室名称：心内科。
单击确定后，最终发送给智能体的 payload 内容为：
{"result": "submit","hospital": "北京301医院","department": "心内科"}
常见问题
为什么我在 Widget 里进行了交互操作，但智能体没有拿到结果？
通常可以从两个方面进行排查：
一是确认是否真正触发了 Action。只有当用户在组件上完成了明确的交互操作（如点击按钮、提交表单），且该组件配置了可触发的 Action（如 onClickAction、onSubmitAction），交互结果才会被发送给智能体；如果 Widget 仅用于内容展示，或只包含输入组件但没有对应的提交动作，智能体是无法感知用户操作的。
二是确认是否使用了正确的 Action 类型。在当前支持的 Action 中，
sys.go_to_url 仅用于页面跳转，不会向智能体传递任何数据，而 sys.chat 会将 payload 作为新的用户输入写入对话上下文，供智能体继续推理与决策。因此，只要希望智能体“看到”并处理用户的操作结果，就必须使用 sys.chat。表单里的 Input 已填写，为什么提交后仍然拿不到对应的值？
这种情况通常由两个原因导致：
其一，Input 未配置
name 字段，没有 name 的输入项不会参与参数提交，例如以下示例中，缺少 name 字段，用户即便填写了内容，也无法提交给智能体。错误示例（缺少
name字段，不会提交）：<FormonSubmitAction={{type: 'sys.chat',payload: { type: 'submit_form' },}}><Input placeholder="医院名称" /><Button submit label="提交" /></Form>
其二，输入组件未通过 Form 表单组件进行提交。Input、Select 等信息收集组件本身不会主动提交数据，必须包裹在 Form 表单组件中，并通过 onSubmitAction 触发表单提交，才能将用户填写的内容统一发送出去。
因此，表单类 Widget 必须满足以下条件：输入组件配置了 name 字段、组件被包裹在 Form 表单组件中，并且通过 onSubmitAction 触发提交。符合规范的示例如下：
<FormonSubmitAction={{type: 'sys.chat',payload: { type: 'submit_form' },}}><Inputname="hospital_name"placeholder="医院名称"required/><Button submit label="提交" style="primary" /></Form>
或者使用具备表单语义的容器组件：
<Cardas="form"onSubmitAction={{type: 'sys.chat',payload: { type: 'submit_form' },}}><Inputname="hospital_name"placeholder="医院名称"required/><Button submit label="提交" /></Card>
如何在 Widget 中实现预填内容，并支持用户修改内容并返回智能体？
在许多交互场景中，Agent 会先向用户展示一个表单或预填信息，用户在此基础上进行修改并提交，希望将修改后的内容重新传回 Agent，用于后续推理或流程决策。这类交互在用户提交个人信息、选择方案或确认内容时尤为常见。
Widget 能够支持这类交互：智能体生成的初始结果可作为
defaultValue 预填到输入组件中，用户修改后，通过 Action 将用户修改后的内容传回智能体。其中 defaultValue 仅用于初始内容展示，作为用户修改的起点，不会直接返回给智能体，真正参与后续推理的内容是用户在输入组件中修改并提交的最终值。以播客内容生成表单为例，具体流程为：智能体生成
initialObject 和 initialScript 的初始默认值作为播客主题及文案的初稿，并通过 defaultValue 预填到输入框中，用户修改后提交表单，智能体最终接收的值是用户确认修改后的播客主题及文案，而非初始默认值。总之，defaultValue 只是展示给用户的初稿，智能体始终接收并处理用户提交的最终结果。Template 示例：
<FormonSubmitAction={{type: 'sys.chat',payload: { type: 'submit_form' },}}><Title value="播客内容生成" size="sm" /><Label value="播客主题" /><Input name="object" defaultValue={initialObject} /><Label value="播客文案" /><Textareaname="script"defaultValue={initialScript}rows={10}autoResizerequired/><Row><Spacer /><Button submit label="提交" style="primary" /></Row></Form>
效果展示：
该播客内容生成表单中的播客主题和播客文案已经通过
defaultValue 预填到输入框，用户可以直接修改并提交，最终内容会传回智能体进行后续处理。
下载按钮希望用户可以反复点击，应该怎么配置？
注意：
该配置适用于下载(
sys.download)、跳转(sys.go_to_url)等可重复执行的操作，不建议用于sys.chat类型的 Action，以避免重复触发对话请求。例如：
<Buttonlabel="下载图片"onClickAction={{type: 'sys.download',alwaysEnabled: true,payload: {url: 'https://cdn.xiaowei.qq.com/static/adp/app-default-avatar.png',},}}/>
文档反馈