腾讯云智能体开发平台 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 发送“重新选择方案”的对话信息。
<Button   
    label="重新选择"  
     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 示例：
<Button   
label="查看详情"   
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 示例：
<Button
  label="下载图片"
  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 目前暂未支持，后续将支持自定义。
在 Multi-Agent 模式中，当 Widget 被 Agent 引用或作为工具调用的直接输出时，如果该 Widget 配置了 Action，相关配置会自动回显到 Widget 设置和预览页面中的交互设置中。
正确配置 Action 的回显
错误配置 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">
  <Form
    onSubmitAction={{
      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" />
        <Button
          label="取消"
          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字段，不会提交）：
<Form
  onSubmitAction={{
    type: 'sys.chat',
    payload: { type: 'submit_form' },
  }}
>
  <Input placeholder="医院名称" />
  <Button submit label="提交" />
</Form>
其二，输入组件未通过 Form 表单组件进行提交。Input、Select 等信息收集组件本身不会主动提交数据，必须包裹在 Form 表单组件中，并通过 onSubmitAction 触发表单提交，才能将用户填写的内容统一发送出去。
因此，表单类 Widget 必须满足以下条件：输入组件配置了 name 字段、组件被包裹在 Form 表单组件中，并且通过 onSubmitAction 触发提交。符合规范的示例如下：
<Form
  onSubmitAction={{
    type: 'sys.chat',
    payload: { type: 'submit_form' },
  }}
>
  <Input
    name="hospital_name"
    placeholder="医院名称"
    required
  />
﻿
  <Button submit label="提交" style="primary" />
</Form>
或者使用具备表单语义的容器组件：
<Card
  as="form"
  onSubmitAction={{
    type: 'sys.chat',
    payload: { type: 'submit_form' },
  }}
>
  <Input
    name="hospital_name"
    placeholder="医院名称"
    required
  />
﻿
  <Button submit label="提交" />
</Card>
如何在 Widget 中实现用户修改内容后，将修改结果返回给 Agent？
在许多交互场景中，Agent 会先向用户展示一个表单或预填信息，用户在此基础上进行修改并提交，希望将修改后的内容重新传回 Agent，用于后续推理或流程决策。这类交互在用户提交个人信息、选择方案或确认内容时尤为常见。Widget 能够支持这类交互，并将用户修改后的内容传回 Agent。
最常见的方式是使用表单组件：当用户修改并提交表单时，表单内所有信息收集字段都会自动合并到 Action 的 payload 中，并通过 sys.chat 传递给智能体，您只需要配置表单和提交动作，系统会自动处理提交数据的传递。例如：
<Form
  onSubmitAction={{
    type: "sys.chat",
    payload: { result: "submit" }
  }}
>
  <Input name="hospital" placeholder="医院名称" />
  <Input name="department" placeholder="科室" />
</Form>
提交后，payload 会自动包含用户填写或修改后的内容，智能体可以直接获取这些内容并参与后续推理。
如果不使用表单，也可以通过手动配置 Action 的方式，在 sys.chat 的 payload 中引用对应的动态字段，将用户修改后的内容一并提交给 AI。例如：
<Button
  label="提交"
  onClickAction={{
    type: "sys.chat",
    payload: {
      hospital: "{{hospital}}",
      department: "{{department}}"
    }
  }}
/>
在该示例中，hospital 和 department 均为动态值，用户修改的内容会在点击按钮时自动传递给 payload，并发送给智能体进行后续处理。
无论采用哪种方式，关键在于通过可触发的 Action 将用户的填写或修改后的输入显式地传递给智能体。 
下载按钮希望用户可以反复点击，应该怎么配置？
在onClickAction 中将 alwaysEnabled 设置为true，即可允许 Button 多次点击；否则按钮默认只可点击一次并会自动禁用，详情可见Button 按钮。
注意：
该配置适用于下载(sys.download)、跳转(sys.go_to_url)等可重复执行的操作，不建议用于sys.chat类型的 Action，以避免重复触发对话请求。
例如：
<Button
  label="下载图片"
  onClickAction={{
    type: 'sys.download',
    alwaysEnabled: true,
    payload: {
      url: 'https://cdn.xiaowei.qq.com/static/adp/app-default-avatar.png',
    },
  }}
/>
﻿
﻿
字段	类型	描述
type	`"sys.chat"` \| `"sys.go_to_url"` \| `"sys.download"`	用于定义用户交互后执行的具体行为类型。
payload	`object`	提供指定 Action 类型所需的数据内容。
Component	Action 属性	说明
Button	onClickAction	点击触发
Form	onSubmitAction	表单提交
DatePicker	onChangeAction	日期变化
Select			选择变化
Checkbox			勾选变化
RadioGroup			单选变化
Widget Action 使用说明

本页目录：

什么是 Action？

官方预置 Action

sys.chat

定义

功能说明

适用场景

示例说明

sys.go_to_url

定义

功能说明

适用场景

示例说明

sys.download

定义

功能说明

适用场景

示例说明

Action 的执行流程

支持 Action 的组件

表单类 Widget 参数提交机制

信息收集类组件

Widget 提交参数

Widget 示例

常见问题

为什么我在 Widget 里进行了交互操作，但智能体没有拿到结果？

表单里的 Input 已填写，为什么提交后仍然拿不到对应的值？

如何在 Widget 中实现用户修改内容后，将修改结果返回给 Agent？

下载按钮希望用户可以反复点击，应该怎么配置？
