CreateAgent - 创建 Agent

更新时间:
复制 MD 格式

创建 Agent

接口说明

请求说明

  • Agent 名称:必须在当前账号下唯一。

  • 模型配置:可选参数,用于指定 Agent 使用的模型及其相关设置。

  • 可见性级别:定义了谁可以访问该 Agent,支持账号内、项目或特定用户可见。

  • 可见性范围:当选择 PROJECT 或 USER 作为可见性级别时,需要进一步指定具体的项目 ID 或用户 ID 列表。

  • 其他参数:如展示名称、描述等为非必填项,可根据实际需求填写。

调试

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

调试

授权信息

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

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

  • 访问级别:是指每个操作的访问级别,取值为写入(Write)、读取(Read)或列出(List)。

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

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

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

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

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

操作

访问级别

资源类型

条件关键字

关联操作

dataworks:CreateAgent

create

*全部资源

*

无 无

请求参数

名称

类型

必填

描述

示例值

Name

string

是

Agent 名称,在当前账号下唯一。

my-agent

DisplayName

string

否

Agent 展示名称。

我的助手

Description

string

否

Agent 描述。

数据分析助手

Model

object

否

模型配置。

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

SystemPrompt

string

否

系统提示词。

你是一个数据分析助手。

Tools

array<object>

否

工具列表。

object

否

工具信息。

BuiltinName

string

否

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

web_search

Kind

string

否

有效工具引用须填写。BUILTIN_TOOLSET 表示内置工具集,须同时填写 BuiltinName;MCP_TOOLSET 表示 MCP 工具集,须同时填写 McpServerName。由目标服务端按工具类型校验。

枚举值:

  • BUILTIN_TOOLSET
  • MCP_TOOLSET

MCP_TOOLSET

McpItems

array

否

Kind 为 MCP_TOOLSET 时可选;填写时限定使用所列工具,省略或空数组表示不按工具名称筛选。每项为目标 MCP 服务中实际存在的工具名称。

string

否

MCP 工具名称

only-this-tool

McpServerName

string

否

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

mcp-a

Name

string

否

McpServer 名称

server-1

Skills

array<object>

否

技能列表。

object

否

技能配置

Name

string

否

Skill 名称

skill-1

SkillId

string

否

Source=OFFICIAL 时传官方目录 ID,不传 Name、Version 或 VersionSelector。个人或企业 Skill 不传此字段。

dataworks-semantic

Source

string

否

OFFICIAL 表示官方目录资源;DB 表示个人或企业资源,省略时保持原有按名称查询语义。

枚举值:

  • DB
  • OFFICIAL

OFFICIAL

Version

integer

否

仅用于个人或企业 Skill,固定已发布快照的整数修订号,与 VersionSelector 互斥。新版发布不改变固定引用;两者均省略时每次新会话跟随 latest。Source=OFFICIAL 时不传。

1

VersionSelector

string

否

仅用于个人或企业资源,与 Version 互斥。支持精确语义版本、latest 和完整 npm/node-semver 范围语法,如 1.2.*、^1.2.3、~1.2.3、>=1.0.0 <2.0.0、1.x || 2.x。两者均省略时按 latest 处理,每次新会话选择最高匹配的已发布版本。已有固定整数引用保持不变。Source=OFFICIAL 时不传。

^1.2.3

ExpertSuites

array<object>

否

Agent 绑定的已发布专家套件。个人或企业套件使用 SuiteId,可选固定 Version 或 VersionSelector;官方套件必须显式指定 Source=OFFICIAL 和官方目录中的 SuiteId,不传 Version 或 VersionSelector。未传时创建为空,不会默认加载所有官方套件。

object

否

Source

string

否

OFFICIAL 表示官方目录资源;DB 表示个人或企业资源。省略时保持原有数据库资源查询语义。官方资源在 Agent 发布时固定制品版本。

枚举值:

  • DB
  • OFFICIAL

OFFICIAL

SuiteId

string

否

传入专家套件引用时,每项需提供 SuiteId,由服务端校验。Source=OFFICIAL 时为官方目录 ID;其他情况为专家套件管理返回的 ID。引用资源必须对调用者可见。

dataworks-data-analysis-extension

Version

integer

否

仅用于个人或企业套件,固定已发布快照的整数修订号,与 VersionSelector 互斥。新版发布不改变固定引用;两者均省略时每次新会话跟随 latest。Source=OFFICIAL 时不传。

1

VersionSelector

string

否

仅用于个人或企业资源,与 Version 互斥。支持精确语义版本、latest 和完整 npm/node-semver 范围语法,如 1.2.*、^1.2.3、~1.2.3、>=1.0.0 <2.0.0、1.x || 2.x。两者均省略时按 latest 处理,每次新会话选择最高匹配的已发布版本。已有固定整数引用保持不变。Source=OFFICIAL 时不传。

^1.2.3

CallableAgents

array<object>

否

可被本 Agent 调用的子 Agent 列表。

object

否

agent 名称

Name

string

否

Agent 名称

agent-1

PublishImmediately

boolean

否

是否在创建 Agent 后立即发布。true 发布创建的版本;false 或省略保持原有仅创建草稿行为。保存与发布不是原子操作,发布失败时草稿可能已存在;重试前应先查询 Agent,避免重复创建。

false

Metadata

object

否

扩展元数据(键值对)。

{}

Visibility

string

否

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







枚举值:

  • PROJECT :

    项目

  • USER :

    用户

  • TENANT :

    租户

TENANT

VisibilityScope

object

否

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

ProjectIds

array

否

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

string

否

工作空间 ID 列表

[21791]

UserIds

array

否

可见的用户 ID 列表,Visibility 为 USER 时生效。

string

否

可见的用户 ID 列表,Visibility 为 USER 时生效。

[]

返回参数

名称

类型

描述

示例值

object

Schema of Response

Agent

object

创建的 Agent 详情

ExpertSuites

array<object>

已保存的套件引用。官方资源返回来源及目录 ID;发布后的制品版本由 PackageVersion 表示。

object

PackageVersion

string

创建时不返回;请使用 GetAgent 显式查询已发布版本获取固定的官方套件制品版本。

0.1.0.202610211408

Source

string

专家套件来源

OFFICIAL

SuiteId

string

专家套件 ID

dataworks-data-analysis-extension

Version

integer

自定义套件发布版本号

1

VersionSelector

string

仅个人或企业资源返回已保存的版本选择策略,与固定整数 Version 互斥;不代表会话实际加载的具体修订。官方资源不返回。

^1.2.3

GmtCreateTime

integer

创建时间(毫秒时间戳)。

1780555634000

GmtModifiedTime

integer

最近修改时间(毫秒时间戳)。

1780555634000

Name

string

Agent 名称。

my-agent

Skills

array<object>

已保存的 Skill 引用;官方 Skill 在 Agent 发布后返回固定的 PackageVersion。

object

Name

string

自定义 Skill 名称

my-business-skill

PackageVersion

string

创建时不返回;请使用 GetAgent 显式查询已发布版本获取固定的官方制品版本。

0.6.0.202608201110

SkillId

string

官方 Skill ID

dataworks-semantic

Source

string

Skill 来源

OFFICIAL

Version

integer

自定义 Skill 发布版本号

1

VersionSelector

string

仅个人或企业资源返回已保存的版本选择策略,与固定整数 Version 互斥;不代表会话实际加载的具体修订。官方资源不返回。

^1.2.3

RequestId

string

请求 ID。

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

示例

正常返回示例

JSON格式

{
  "Agent": {
    "ExpertSuites": [
      {
        "PackageVersion": "0.1.0.202610211408",
        "Source": "OFFICIAL",
        "SuiteId": "dataworks-data-analysis-extension",
        "Version": 1,
        "VersionSelector": "^1.2.3"
      }
    ],
    "GmtCreateTime": 1780555634000,
    "GmtModifiedTime": 1780555634000,
    "Name": "my-agent",
    "Skills": [
      {
        "Name": "my-business-skill",
        "PackageVersion": "0.6.0.202608201110",
        "SkillId": "dataworks-semantic",
        "Source": "OFFICIAL",
        "Version": 1,
        "VersionSelector": "^1.2.3"
      }
    ]
  },
  "RequestId": "824F80BA-1778-5D8A-BAFF-668A4D9C4CC7"
}

错误码

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

变更历史

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