查询智能体列表

列出当前身份在目标工作区中可使用的智能体。结果可能同时包含当前工作区创建的自定义智能体和该工作区可使用的系统智能体。可按状态、关键词和展示场景筛选,并通过分页参数分段读取。

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents

调用前准备

准备可访问目标工作区的个人访问令牌和目标工作区 ID。

请求参数

curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "surface=agent_chat" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

路径参数

字段

类型

是否必填

说明

workspace_id

string

是

当前工作区 ID,必须与 X-Workspace-ID 一致。

catalog

string

否

目录选择。取值为 空字符串、workspace、system。

include_development

boolean

否

是否包含开发项。

查询参数

字段

类型

是否必填

说明

status

string

否

按智能体状态筛选。

query

string

否

按关键词筛选。

surface

string

否

展示场景。仅接受 agent_chat。

limit

integer

否

单次返回数量。未提供或小于等于 0 时为 50,最大为 200。

offset

integer

否

返回偏移量。未提供或小于 0 时为 0。

catalog 省略时合并工作区和系统目录。填写 workspace 或 system 时只列对应目录。include_development 仅在值为 true 或 1 时启用开发项。

成功响应

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "agent_01",
        "workspace_id": "ws_01",
        "schema_version": 1,
        "name": "销售助手",
        "instruction": {
          "system_prompt": "分析销售数据"
        },
        "runtime": {
          "provider": "matrixone",
          "profile": "default"
        },
        "status": "active",
        "version": 1,
        "source_type": "custom",
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-15T10:00:00Z",
        "model": {},
        "binding": {},
        "policy_refs": {},
        "workflow_refs": {},
        "lifecycle": {}
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

字段

类型

说明

code

integer

成功代码。

data

object

本次操作返回的数据。

data.items

object(对象数组)

本页智能体列表。

data.items[].id

string

智能体 ID。

data.items[].workspace_id

string

智能体定义所属的工作区 ID。系统智能体可能与当前请求工作区不同。

data.items[].schema_version

integer

智能体元数据结构版本。

data.items[].name

string

智能体名称和说明。

data.items[].description

string

智能体名称和说明。

data.items[].avatar_ref

string

头像引用。

data.items[].icon

string

展示图标。

data.items[].display_tags

string(字符串数组) 或 null

用于展示的标签。

data.items[].category

string

分类。

data.items[].sort_order

integer

显示顺序。

data.items[].instruction

object

指令配置。

data.items[].instruction.system_prompt

string

系统提示词。

data.items[].instruction.behavior_rules

string(字符串数组) 或 null

行为规则。

data.items[].instruction.output_contract_ref

string

输出格式约定的引用。

data.items[].instruction.variables_schema

JSON 值

变量定义。

data.items[].runtime

object

运行目标,包含 provider、profile 和可选 config。

data.items[].runtime.provider

string

运行提供方。

data.items[].runtime.profile

string

运行配置名称。

data.items[].runtime.config

JSON 值

配置对象。

data.items[].model

object

模型配置和资源绑定。

data.items[].model.model_config_ref

string

模型配置 ID。

data.items[].model.default_model

string

默认模型。

data.items[].model.params_override

JSON 值

模型参数覆盖。

data.items[].binding

object

模型配置和资源绑定。

data.items[].binding.skill_refs

object(对象数组) 或 null

技能绑定引用。

data.items[].binding.skill_refs[].id

string

被引用技能的资源 ID。

data.items[].binding.skill_refs[].workspace_id

string

所属工作区 ID。

data.items[].binding.skill_refs[].kind

string

被引用资源的类型。取值为 skill、tool、knowledge_base

data.items[].binding.skill_refs[].status

string

状态。

data.items[].binding.skill_refs[].resource_id

string

资源 ID。

data.items[].binding.skill_refs[].name

string

当前对象的名称。

data.items[].binding.skill_refs[].display_name

string

显示名称。

data.items[].binding.skill_refs[].description

string

当前对象的说明。

data.items[].binding.skill_refs[].category

string

分类。

data.items[].binding.skill_refs[].phase

string

阶段。

data.items[].binding.skill_refs[].bindable

boolean

当前智能体是否可以绑定该资源。

data.items[].binding.skill_refs[].bindability_reason

string

绑定限制原因。

data.items[].binding.skill_refs[].supported_runtimes

string(字符串数组) 或 null

支持的运行环境。

data.items[].binding.skill_refs[].config

JSON 值

配置对象。

data.items[].binding.skill_refs[].runtime_tool_visibility

string

运行时工具可见范围。

data.items[].binding.skill_refs[].binding_source

string

绑定来源。

data.items[].binding.skill_refs[].manageable

boolean

是否可管理。

data.items[].binding.tool_refs

object(对象数组) 或 null

工具引用。

data.items[].binding.tool_refs[].id

string

当前对象的 ID。

data.items[].binding.tool_refs[].workspace_id

string

所属工作区 ID。

data.items[].binding.tool_refs[].kind

string

资源类型。取值为 skill、tool、knowledge_base

data.items[].binding.tool_refs[].status

string

状态。

data.items[].binding.tool_refs[].resource_id

string

资源 ID。

data.items[].binding.tool_refs[].name

string

当前对象的名称。

data.items[].binding.tool_refs[].display_name

string

显示名称。

data.items[].binding.tool_refs[].description

string

当前对象的说明。

data.items[].binding.tool_refs[].category

string

分类。

data.items[].binding.tool_refs[].phase

string

阶段。

data.items[].binding.tool_refs[].bindable

boolean

是否可绑定。

data.items[].binding.tool_refs[].bindability_reason

string

绑定限制原因。

data.items[].binding.tool_refs[].supported_runtimes

string(字符串数组) 或 null

支持的运行环境。

data.items[].binding.tool_refs[].config

JSON 值

配置对象。

data.items[].binding.tool_refs[].runtime_tool_visibility

string

运行时工具可见范围。

data.items[].binding.tool_refs[].binding_source

string

绑定来源。

data.items[].binding.tool_refs[].manageable

boolean

是否可管理。

data.items[].binding.knowledge_base_refs

object(对象数组) 或 null

知识库引用。

data.items[].binding.knowledge_base_refs[].id

string

当前对象的 ID。

data.items[].binding.knowledge_base_refs[].workspace_id

string

所属工作区 ID。

data.items[].binding.knowledge_base_refs[].kind

string

资源类型。取值为 skill、tool、knowledge_base

data.items[].binding.knowledge_base_refs[].status

string

状态。

data.items[].binding.knowledge_base_refs[].resource_id

string

资源 ID。

data.items[].binding.knowledge_base_refs[].name

string

当前对象的名称。

data.items[].binding.knowledge_base_refs[].display_name

string

显示名称。

data.items[].binding.knowledge_base_refs[].description

string

当前对象的说明。

data.items[].binding.knowledge_base_refs[].category

string

分类。

data.items[].binding.knowledge_base_refs[].phase

string

阶段。

data.items[].binding.knowledge_base_refs[].bindable

boolean

是否可绑定。

data.items[].binding.knowledge_base_refs[].bindability_reason

string

绑定限制原因。

data.items[].binding.knowledge_base_refs[].supported_runtimes

string(字符串数组) 或 null

支持的运行环境。

data.items[].binding.knowledge_base_refs[].config

JSON 值

配置对象。

data.items[].binding.knowledge_base_refs[].runtime_tool_visibility

string

运行时工具可见范围。

data.items[].binding.knowledge_base_refs[].binding_source

string

绑定来源。

data.items[].binding.knowledge_base_refs[].manageable

boolean

是否可管理。

data.items[].binding.channel_bindings

object(对象数组) 或 null

通道绑定。

data.items[].binding.channel_bindings[].provider

string

运行提供方。

data.items[].binding.channel_bindings[].channel_type

string

通道类型。

data.items[].binding.channel_bindings[].channel_instance_ids

string(字符串数组) 或 null

通道实例 ID。

data.items[].policy_refs

object

策略和工作流引用。

data.items[].policy_refs.runtime_policy_ref

string

运行策略 ID。

data.items[].policy_refs.approval_policy_ref

string

审批策略 ID。

data.items[].policy_refs.guardrail_policy_ref

string

护栏策略 ID。

data.items[].workflow_refs

object

策略和工作流引用。

data.items[].workflow_refs.default_task_template_ids

string(字符串数组) 或 null

默认任务模板 ID。

data.items[].lifecycle

object

生命周期信息。

data.items[].lifecycle.draft_ref

string

资源引用。

data.items[].lifecycle.published_version

integer

已发布版本。

data.items[].status

string

智能体状态和资源版本。取值为 draft、active、disabled、archived

data.items[].version

integer

智能体状态和资源版本。

data.items[].labels

JSON 值

标签键值对。

data.items[].annotations

JSON 值

注解键值对。

data.items[].source_type

string

智能体来源。custom 表示工作区创建的智能体,system 表示系统提供的智能体。取值为 custom、system

data.items[].source_ref

string

来源类型和来源引用。

data.items[].metadata

JSON 值

扩展元数据。

data.items[].created_by

string

创建者标识。

data.items[].updated_by

string

最近更新者标识。

data.items[].created_at

string

创建和最近更新时间,采用 RFC 3339 格式。

data.items[].updated_at

string

创建和最近更新时间,采用 RFC 3339 格式。

data.total

integer

符合筛选条件且当前身份可读取的智能体总数。

data.limit

integer

本次实际采用的分页值。

data.offset

integer

本次实际采用的分页值。

错误响应

{
  "code": 2,
  "message": "invalid agent resource request"
}

常见 HTTP 错误

HTTP 状态码

错误代码

常见原因

建议操作

400

2

请求字段、工作区或操作前置条件无效。

修正参数后再提交。

401

6

认证凭据缺失或无效。

检查凭据类型、有效期及认证头。

403

5、7

当前身份或有效角色无执行该操作的权限。

使用有权限的身份,或联系管理员授权。

404

3

目标对象或所需引用未找到。

核对对象标识、所属工作区和当前状态。

409

4

资源状态、请求内容或并发条件冲突。

重新读取当前状态和版本,按实际结果处理。

500

15

内部处理失败;写操作可能已有部分效果。

保留请求和追踪信息,先核对当前结果。

503

15

业务、运行时或授权依赖暂不可用。

恢复依赖后先核对已有结果,不自动重复写入。

最后更新于