查询智能体任务模板列表

查询工作区中的智能体任务模板，可按关联智能体、状态或名称筛选。

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-task-templates

调用前准备

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

请求参数

输入示例

curl "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-task-templates?limit=20&offset=0" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

参数说明

路径参数

参数	类型	是否必填	说明
workspace_id	string	是	目标工作区 ID。

查询参数

参数	类型	是否必填	说明
agent_id	string	否	关联智能体 ID。
status	string	否	模板状态。
query	string	否	按模板名称或说明筛选。
limit	integer	否	返回数量。
offset	integer	否	返回起始位置。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "template_01",
        "workspace_id": "workspace_example",
        "agent_id": "agent_01",
        "name": "摘要任务",
        "message_template": {
          "role": "user",
          "template": "请总结输入内容"
        },
        "idempotency_policy": {
          "mode": "workflow_case"
        },
        "status": "draft",
        "version": 1,
        "created_at": "2026-10-14T00:00:00Z",
        "updated_at": "2026-10-14T00:00:00Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

字段说明

字段	类型	说明
code	integer	请求处理成功时为 0。
data	object	响应数据。
data.items	object（对象数组）	本次返回的记录。
data.items[].id	string	对象 ID。
data.items[].workspace_id	string	所属工作区 ID。
data.items[].agent_id	string	关联的智能体 ID。
data.items[].name	string	名称。
data.items[].description	string	说明。未设置时可省略。
data.items[].message_template	object	消息模板。
data.items[].input_schema	object	输入参数的 JSON Schema。未设置时可省略。
data.items[].default_context_refs	object（对象数组）	默认上下文资源引用。未设置时可省略。
data.items[].default_context_refs[].id	string	对象 ID。
data.items[].runtime_policy_ref	string	运行策略引用。未设置时可省略。
data.items[].idempotency_policy	object	幂等策略。
data.items[].idempotency_policy.mode	string	策略或范围模式。取值：none、workflow_case、custom。
data.items[].idempotency_policy.key_template	string	自定义幂等键模板。未设置时可省略。
data.items[].idempotency_policy.window_seconds	integer	幂等窗口，单位为秒。未设置时可省略。
data.items[].output_contract	object	输出约定。未设置时可省略。
data.items[].status	string	当前状态。取值：draft、active、disabled、archived。
data.items[].version	integer	当前版本号。
data.items[].labels	object	标签键值对。未设置时可省略。
data.items[].annotations	object	扩展注解。未设置时可省略。
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	本次查询使用的偏移量。
data.items[].message_template.role	string	消息角色。
data.items[].message_template.template	string	消息模板文本。使用 parts 时可省略。
data.items[].message_template.parts	array 或 null	结构化消息组成项，内容由模板保留。
data.items[].message_template.variables	object 或 null	模板变量。
data.items[].default_context_refs[].type	string	上下文资源类型。
data.items[].default_context_refs[].uri	string	资源地址。使用 id 时可省略。
data.items[].default_context_refs[].version	string	资源版本。未设置时省略。
data.items[].default_context_refs[].config	object 或 null	资源配置。未设置时省略。

错误响应

响应示例

{
  "code": 2,
  "message": "invalid agent task template filter"
}

字段说明

常见 HTTP 错误

HTTP 状态码	错误代码	说明
400	2	**常见原因：**筛选或分页参数无效。**建议操作：**检查查询参数。
401	6	**常见原因：**缺少有效身份凭据。**建议操作：**检查 API Key。

最后更新于 2026 年 10 月 19 日