查询智能体列表¶
列出当前身份在目标工作区中可使用的智能体。结果可能同时包含当前工作区创建的自定义智能体和该工作区可使用的系统智能体。可按状态、关键词和展示场景筛选,并通过分页参数分段读取。
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"
路径参数
字段 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
当前工作区 ID,必须与 X-Workspace-ID 一致。 |
|
string |
否 |
目录选择。取值为 空字符串、 |
|
boolean |
否 |
是否包含开发项。 |
查询参数
字段 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
否 |
按智能体状态筛选。 |
|
string |
否 |
按关键词筛选。 |
|
string |
否 |
展示场景。仅接受 agent_chat。 |
|
integer |
否 |
单次返回数量。未提供或小于等于 0 时为 50,最大为 200。 |
|
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
}
}
字段 |
类型 |
说明 |
|---|---|---|
|
integer |
成功代码。 |
|
object |
本次操作返回的数据。 |
|
object(对象数组) |
本页智能体列表。 |
|
string |
智能体 ID。 |
|
string |
智能体定义所属的工作区 ID。系统智能体可能与当前请求工作区不同。 |
|
integer |
智能体元数据结构版本。 |
|
string |
智能体名称和说明。 |
|
string |
智能体名称和说明。 |
|
string |
头像引用。 |
|
string |
展示图标。 |
|
string(字符串数组) 或 null |
用于展示的标签。 |
|
string |
分类。 |
|
integer |
显示顺序。 |
|
object |
指令配置。 |
|
string |
系统提示词。 |
|
string(字符串数组) 或 null |
行为规则。 |
|
string |
输出格式约定的引用。 |
|
JSON 值 |
变量定义。 |
|
object |
运行目标,包含 provider、profile 和可选 config。 |
|
string |
运行提供方。 |
|
string |
运行配置名称。 |
|
JSON 值 |
配置对象。 |
|
object |
模型配置和资源绑定。 |
|
string |
模型配置 ID。 |
|
string |
默认模型。 |
|
JSON 值 |
模型参数覆盖。 |
|
object |
模型配置和资源绑定。 |
|
object(对象数组) 或 null |
技能绑定引用。 |
|
string |
被引用技能的资源 ID。 |
|
string |
所属工作区 ID。 |
|
string |
被引用资源的类型。取值为 |
|
string |
状态。 |
|
string |
资源 ID。 |
|
string |
当前对象的名称。 |
|
string |
显示名称。 |
|
string |
当前对象的说明。 |
|
string |
分类。 |
|
string |
阶段。 |
|
boolean |
当前智能体是否可以绑定该资源。 |
|
string |
绑定限制原因。 |
|
string(字符串数组) 或 null |
支持的运行环境。 |
|
JSON 值 |
配置对象。 |
|
string |
运行时工具可见范围。 |
|
string |
绑定来源。 |
|
boolean |
是否可管理。 |
|
object(对象数组) 或 null |
工具引用。 |
|
string |
当前对象的 ID。 |
|
string |
所属工作区 ID。 |
|
string |
资源类型。取值为 |
|
string |
状态。 |
|
string |
资源 ID。 |
|
string |
当前对象的名称。 |
|
string |
显示名称。 |
|
string |
当前对象的说明。 |
|
string |
分类。 |
|
string |
阶段。 |
|
boolean |
是否可绑定。 |
|
string |
绑定限制原因。 |
|
string(字符串数组) 或 null |
支持的运行环境。 |
|
JSON 值 |
配置对象。 |
|
string |
运行时工具可见范围。 |
|
string |
绑定来源。 |
|
boolean |
是否可管理。 |
|
object(对象数组) 或 null |
知识库引用。 |
|
string |
当前对象的 ID。 |
|
string |
所属工作区 ID。 |
|
string |
资源类型。取值为 |
|
string |
状态。 |
|
string |
资源 ID。 |
|
string |
当前对象的名称。 |
|
string |
显示名称。 |
|
string |
当前对象的说明。 |
|
string |
分类。 |
|
string |
阶段。 |
|
boolean |
是否可绑定。 |
|
string |
绑定限制原因。 |
|
string(字符串数组) 或 null |
支持的运行环境。 |
|
JSON 值 |
配置对象。 |
|
string |
运行时工具可见范围。 |
|
string |
绑定来源。 |
|
boolean |
是否可管理。 |
|
object(对象数组) 或 null |
通道绑定。 |
|
string |
运行提供方。 |
|
string |
通道类型。 |
|
string(字符串数组) 或 null |
通道实例 ID。 |
|
object |
策略和工作流引用。 |
|
string |
运行策略 ID。 |
|
string |
审批策略 ID。 |
|
string |
护栏策略 ID。 |
|
object |
策略和工作流引用。 |
|
string(字符串数组) 或 null |
默认任务模板 ID。 |
|
object |
生命周期信息。 |
|
string |
资源引用。 |
|
integer |
已发布版本。 |
|
string |
智能体状态和资源版本。取值为 |
|
integer |
智能体状态和资源版本。 |
|
JSON 值 |
标签键值对。 |
|
JSON 值 |
注解键值对。 |
|
string |
智能体来源。 |
|
string |
来源类型和来源引用。 |
|
JSON 值 |
扩展元数据。 |
|
string |
创建者标识。 |
|
string |
最近更新者标识。 |
|
string |
创建和最近更新时间,采用 RFC 3339 格式。 |
|
string |
创建和最近更新时间,采用 RFC 3339 格式。 |
|
integer |
符合筛选条件且当前身份可读取的智能体总数。 |
|
integer |
本次实际采用的分页值。 |
|
integer |
本次实际采用的分页值。 |
错误响应¶
{
"code": 2,
"message": "invalid agent resource request"
}
常见 HTTP 错误¶
HTTP 状态码 |
错误代码 |
常见原因 |
建议操作 |
|---|---|---|---|
400 |
|
请求字段、工作区或操作前置条件无效。 |
修正参数后再提交。 |
401 |
|
认证凭据缺失或无效。 |
检查凭据类型、有效期及认证头。 |
403 |
|
当前身份或有效角色无执行该操作的权限。 |
使用有权限的身份,或联系管理员授权。 |
404 |
|
目标对象或所需引用未找到。 |
核对对象标识、所属工作区和当前状态。 |
409 |
|
资源状态、请求内容或并发条件冲突。 |
重新读取当前状态和版本,按实际结果处理。 |
500 |
|
内部处理失败;写操作可能已有部分效果。 |
保留请求和追踪信息,先核对当前结果。 |
503 |
|
业务、运行时或授权依赖暂不可用。 |
恢复依赖后先核对已有结果,不自动重复写入。 |