AI 助理
文档备案控制台
官方文档
首页 大数据开发治理平台 DataWorks 开发参考 API参考（2024-05-18） API目录 Data Agent 智能体管理 / Agent UpdateAgent - 更新 Agent 定义

UpdateAgent - 更新 Agent 定义

更新时间：
复制 MD 格式
产品详情
我的收藏

更新指定 Agent 的定义并递增定义版本，可选择立即发布。本接口需要开启灰度才可以使用。调用前请确认当前账号及目标地域已开启相应灰度。

接口说明

本接口需要开启灰度才可以使用。调用前请确认当前账号及目标地域已开启相应灰度。

更新当前身份有管理权限的自定义 Agent。Name 用于定位目标，不用于重命名。先调用 GetAgent 读取当前 AgentVersion，更新时显式传入 ExpectedVersion；冲突后重新读取并核对差异，不盲目覆盖。

不需要修改的引用列表应省略。当前新后端对 Tools、Skills、CallableAgents 的空数组保留已有引用，对 ExpertSuites 的空数组清空引用；不能使用统一的空数组清空规则。Tools 已包含 Kind 及对应工具配置，与 CreateAgent 使用相同结构；单独填写 Name 不是有效工具配置。

官方 Skill 仅填写 Source=OFFICIAL 与 SkillId；官方套件仅填写 Source=OFFICIAL 与 SuiteId，不混入名称、版本或制品字段。自定义资源的整数 Version 与 VersionSelector 互斥，版本选择能力以目标服务端部署为准。

PublishImmediately 省略或 false 时仅保存定义；true 时先保存新草稿版本再请求发布。保存与发布不是原子操作；发布失败时草稿版本可能已递增，应先 GetAgent 回读，再决定重试，避免重复生成版本。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

  • 操作：是指具体的权限点。

  • 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。

  • 资源类型：是指操作中支持授权的资源类型。具体说明如下：

    • 对于必选的资源类型，用前面加 * 表示。

    • 对于不支持资源级授权的操作，用全部资源表示。

  • 条件关键字：是指云产品自身定义的条件关键字。

  • 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

dataworks:UpdateAgent

update

*全部资源

*

 无 无

请求参数

名称

类型

必填

描述

示例值
Name

string

是

待更新 Agent 的名称，使用 GetAgent 返回的 Name；本字段定位目标，不用于重命名。

my-agent
ExpectedVersion

integer

否

用于并发控制的 Agent 定义版本。建议每次调用都显式填写刚从 GetAgent 取得的 AgentVersion；与服务端当前版本不一致时拒绝更新。为兼容不同部署版本，不依赖省略此参数时的服务端处理。

2
DisplayName

string

否

Agent 展示名称。

我的助手
Description

string

否

Agent 描述。

数据分析助手
Model

object

否

模型配置。

{ "modelName": "dataworks-public-bailian/qwen-max" }
SystemPrompt

string

否

系统提示词。

你是一名优秀的etl工程师。
Tools

array<object>

否

工具引用列表。不需要修改时省略；当前新后端对空数组也保留已有工具。非空数组替换引用，每项需填写 Kind 及对应配置，不能只填写 Name。示例中的 MCP 服务和工具名称应替换为当前身份可用的真实值。

[{"Kind":"MCP_TOOLSET","McpServerName":"mcp-a","McpItems":["only-this-tool"]}]

object

否

单个工具引用，与 CreateAgent、UpdateAgent 使用相同的结构。

{"Kind":"MCP_TOOLSET","McpServerName":"mcp-a","McpItems":["only-this-tool"]}
Kind

string

否

工具类型。有效工具引用须填写 BUILTIN_TOOLSET 或 MCP_TOOLSET；前者需同时填写 BuiltinName，后者需同时填写 McpServerName。由目标服务端按工具类型校验。

枚举值：

  • BUILTIN_TOOLSET :

    内置工具集

  • MCP_TOOLSET :

    MCP 工具集

MCP_TOOLSET
BuiltinName

string

否

内置工具集名称，Kind=BUILTIN_TOOLSET 时必填，使用目标服务端支持的名称；Kind=MCP_TOOLSET 时省略。

web_search
McpServerName

string

否

MCP 服务名称，Kind=MCP_TOOLSET 时必填，必须为当前调用者有权引用且具备可用发布版本的服务。

mcp-a
McpItems

array

否

选用的 MCP 工具名称列表；省略或空数组表示不按工具名称筛选。每项必须是目标服务中实际存在的工具名称。

["only-this-tool"]

string

否

单个 MCP 工具名称，必须来自目标 MCP 服务。

only-this-tool
Name

string

否

旧模型保留字段。单独填写 Name 不构成有效工具配置，不能代替 Kind、BuiltinName 或 McpServerName。

search_tables
Skills

array<object>

否

Skill 引用列表。不需要修改时省略，不用空数组表达保留或清空。官方 Skill 只填写 Source=OFFICIAL 与 SkillId，不接受 Name、Version、VersionSelector 或客户端制品字段；自定义 Skill 填写 Name，可显式指定已有的整数 Version。

[{"Source":"OFFICIAL","SkillId":"dataworks-semantic"}]

object

否

单个 Skill 引用。官方引用只包含 Source 和 SkillId；不要混入自定义资源的名称或版本选择字段。

{"Source":"OFFICIAL","SkillId":"dataworks-semantic"}
Source

string

否

Skill 来源。OFFICIAL：官方 Skill，搭配 SkillId；DB 或省略：自定义 Skill，搭配 Name。

枚举值：

  • OFFICIAL :

    官方资源

  • DB :

    自定义资源

OFFICIAL
SkillId

string

否

官方 Skill 的资源 ID，Source 为 OFFICIAL 时使用。

dataworks-semantic
Name

string

否

自定义 Skill 名称，使用可见的自定义 Skill 的 Name；官方 Skill 使用 SkillId。

my-business-skill
Version

integer

否

自定义 Skill 的已发布整数版本号，用于明确选择已有版本。Source=OFFICIAL 时不要传此字段；不与 VersionSelector 同时传入。

1
VersionSelector

string

否

自定义 Skill 的语义版本选择表达式，例如 ^1.2.3。仅在目标服务端已部署自定义资源版本选择能力时使用，与 Version 互斥。Source=OFFICIAL 时不接受此字段。需要兼容未确认版本的服务端时，使用已有的整数 Version。

^1.2.3
ExpertSuites

array<object>

否

专家套件引用列表。省略保留；显式空数组清空引用。官方套件只填写 Source=OFFICIAL 和 SuiteId，不接受 Version、VersionSelector 或客户端制品字段。自定义套件使用 SuiteId，可显式指定已有的整数 Version。

[{"SuiteId":"suite_example","Version":3}]

object

否

Source

string

否

专家套件来源。OFFICIAL：官方套件；DB 或省略：自定义套件。两类引用均使用 SuiteId，版本字段仅适用于自定义资源。

枚举值：

  • OFFICIAL :

    官方资源

  • DB :

    自定义资源

OFFICIAL
SuiteId

string

否

目标专家套件 ID，必须为当前调用者有权引用的套件。

suite_example
Version

integer

否

自定义专家套件的已发布整数版本号，用于明确选择已有版本。Source=OFFICIAL 时不要传此字段；不与 VersionSelector 同时传入。为获得明确可复现的引用，不依赖省略版本时的默认选择。

3
VersionSelector

string

否

自定义专家套件的语义版本选择表达式，例如 ^1.2.3。仅在目标服务端已部署自定义资源版本选择能力时使用，与 Version 互斥。Source=OFFICIAL 时不接受此字段。需要兼容未确认版本的服务端时，使用已有的整数 Version。

^1.2.3
CallableAgents

array<object>

否

可调用的子 Agent 引用列表。非空引用必须可见，不能引用自身或形成调用环。不需要修改时省略本参数，不用空数组表达通用的保留或清空语义。

[{"Name":"data-analysis"}]

object

否

单个可调用子 Agent 的引用。

{"Name":"data-analysis"}
Name

string

否

被调用的子 Agent 名称，必须为当前调用者有权使用的 Agent。

data-analysis
PublishImmediately

boolean

否

是否更新后立即发布。true：先保存新草稿版本再请求发布；false 或省略：只保存定义。保存与发布不是原子操作，失败后先 GetAgent 回读当前版本，不盲目重复更新。

false
Metadata

object

否

扩展元数据。省略时保留；传入时更新业务元数据，服务端保留受保护的系统元数据。

{}
Visibility

string

否

可见性级别。
TENANT：账号内可见；
PROJECT：指定项目可见；
USER：指定用户可见。







枚举值：

  • PROJECT :

    指定项目可见

  • USER :

    指定用户可见

  • TENANT :

    账号内可见

TENANT
VisibilityScope

object

否

可见性范围，按 Visibility 取对应字段。

ProjectIds

array

否

可见的项目 ID 列表，Visibility 为 PROJECT 时生效。

string

否

单个可见项目 ID。

24180
UserIds

array

否

可见用户 ID 列表，Visibility 为 USER 时使用。

string

否

用户 ID

123456

参数按顶层表单字段提交；Model、Tools、Skills、ExpertSuites、CallableAgents、Metadata、VisibilityScope 等结构参数使用 JSON 编码。最小兼容示例：Name=my-agent、ExpectedVersion=2、Description=数据分析助手、PublishImmediately=false。该示例仅更新描述，未提供的引用字段保留。实际 Name 和 ExpectedVersion 必须使用目标 Agent 刚读取的真实值。

返回参数

名称

类型

描述

示例值

object

Agent 更新响应，包含更新后的 Agent 定义和 OpenAPI 请求 ID。

RequestId

string

请求 ID。

824F80BA-1778-5D8A-BAFF-668A4D9C4CC7
Agent

object

更新后的 Agent 详情

AgentVersion

integer

更新后的 Agent 定义版本

3
Name

string

Agent 名称。

my-agent
Skills

array<object>

更新后绑定的 Skill 引用列表。

object

Source

string

Skill 来源

OFFICIAL
SkillId

string

官方 Skill ID

dataworks-semantic
Name

string

绑定的自定义 Skill 名称。

my-business-skill
Version

integer

绑定的自定义 Skill 发布版本号。

1
VersionSelector

string

版本选择表达式

^1.2.3
ExpertSuites

array<object>

绑定的专家套件

object

Source

string

专家套件来源

OFFICIAL
SuiteId

string

专家套件 ID

suite_example
Version

integer

绑定的发布版本号

3
VersionSelector

string

版本选择表达式

^1.2.3
Name

string

绑定版本的套件名称

analysis-suite
DisplayName

string

绑定版本的展示名称

数据分析专家套件
Description

string

绑定版本的套件描述

数据分析专家能力集合
SemanticVersion

string

绑定版本的语义版本

1.2.0
GmtCreateTime

integer

Agent 创建时间，Unix 时间戳，单位为毫秒。

1780555634000
GmtModifiedTime

integer

Agent 最近修改时间，Unix 时间戳，单位为毫秒。

1780555634000

返回更新后的 Agent 定义及请求 ID。GmtCreateTime、GmtModifiedTime 表达 Unix 毫秒时间戳，应按毫秒时间戳处理，不将其当作 ISO 日期字符串解析。引用资源的补充字段依 Source 和返回内容读取，不假设官方资源一定具有自定义资源版本字段。

示例

正常返回示例

JSON格式

{
  "RequestId": "824F80BA-1778-5D8A-BAFF-668A4D9C4CC7",
  "Agent": {
    "AgentVersion": 3,
    "Name": "my-agent",
    "Skills": [
      {
        "Source": "OFFICIAL",
        "SkillId": "dataworks-semantic",
        "Name": "my-business-skill",
        "Version": 1,
        "VersionSelector": "^1.2.3"
      }
    ],
    "ExpertSuites": [
      {
        "Source": "OFFICIAL",
        "SuiteId": "suite_example",
        "Version": 3,
        "VersionSelector": "^1.2.3",
        "Name": "analysis-suite",
        "DisplayName": "数据分析专家套件",
        "Description": "数据分析专家能力集合",
        "SemanticVersion": "1.2.0"
      }
    ],
    "GmtCreateTime": 1780555634000,
    "GmtModifiedTime": 1780555634000
  }
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。

上一篇：ListAgents - 查询Agent列表下一篇：会话管理 / Agent Session