执行技能¶

提交一个技能运行请求。成功响应为 202 Accepted，只表示请求已被受理，不表示技能已完成执行。

POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/skills/{skill_id}/execute

调用前准备¶

先查询技能详情确认技能为活动状态。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和技能 ID。

至少提供 message、parts、variables 或 resource_refs 中的一项。只有 active 状态的技能可以执行。执行还需要已验证的有效角色和运行时准入授权。

路径参数¶

参数	类型	是否必填	说明
`workspace_id`	string	是	执行工作区 ID。
`skill_id`	string	是	要执行的技能 ID。

查询参数¶

参数	类型	是否必填	说明
`skill_workspace_id`	string	否	技能所属工作区；仅可为当前工作区或 `system`。未提供时先查当前工作区，再查系统技能。

请求体¶

调用示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/skills/$SKILL_ID/execute" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "请总结这段内容。",
    "idempotency_key": "<IDEMPOTENCY_KEY>"
  }'

参数说明

参数	类型	是否必填	说明
`agent_id`	string	否	可选的执行智能体 ID。指定时，该智能体必须为活动状态且已绑定当前技能。
`context_id`	string	否	上下文 ID 和文本输入。
`message`	string	否	上下文 ID 和文本输入。
`parts`	array	否	结构化输入片段。
`variables`	object	否	技能变量和参数。
`parameters`	object	否	技能变量和参数。
`resource_refs`	array	否	资源引用。每项必须包含 `type`，并至少包含 `id` 或 `uri`；可包含 `role`、`version` 和 `config`。
`idempotency_key`	string	否	幂等键。
`metadata`	object	否	扩展元数据。变量、参数、输入片段和元数据中不能包含密钥或运行会话引用。

成功响应¶

响应示例

{
  "code": 0,
  "data": {
    "id": "exec_01",
    "workspace_id": "ws_01",
    "skill_id": "skill_01",
    "skill_version": 2,
    "runtime_task_id": "task_01",
    "runtime_task_url": "/runtime/tasks/task_01",
    "status": "accepted",
    "accepted_at": "2026-01-02T15:04:05Z"
  }
}

字段说明

成功时返回 202。使用 runtime_task_id 或 runtime_task_url 跟踪后续运行状态和结果（字段仅在运行时返回时出现）。

响应字段如下。

通用字段

字段	类型	说明
`code`	integer	成功时为 `0`。

基本信息

字段	类型	说明
`id`	string	执行记录 ID、执行工作区和技能 ID。
`workspace_id`	string	执行记录 ID、执行工作区和技能 ID。
`skill_id`	string	执行记录 ID、执行工作区和技能 ID。
`skill_version`	integer	本次提交使用的技能版本。
`agent_id`	string	关联的智能体和上下文；未提供时不返回。
`context_id`	string	关联的智能体和上下文；未提供时不返回。
`runtime_task_id`	string	运行时任务标识和查询地址；可用时返回。
`runtime_task_url`	string	运行时任务标识和查询地址；可用时返回。
`status`	string	当前受理状态，不代表运行已完成。
`metadata`	object	运行时返回的元数据；可用时返回。
`accepted_at`	string	请求受理时间，使用 RFC 3339 格式。

错误响应¶

响应示例

{
  "code": 2,
  "message": "<错误信息>"
}

字段说明

常见 HTTP 错误

通用字段

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	常见原因：输入为空、资源引用无效、技能未激活，或指定智能体未绑定该技能。建议操作：补齐输入，使用活动技能，并检查资源和智能体绑定。
`401`	`6`（`UNAUTHENTICATED`）	常见原因：缺少有效身份凭据。建议操作：检查 API Key。
`403`	`7`（`FORBIDDEN`）	常见原因：有效角色或运行时准入未获授权。建议操作：检查工作区角色和运行时使用权限。
`404`	`3`（`NOT_FOUND`）	常见原因：当前和可回退的系统目录中均不存在该技能。建议操作：检查技能 ID 和 `skill_workspace_id`。
`503`	`15`（`UNAVAILABLE`）	常见原因：技能执行提交器、运行时准入或授权依赖暂不可用。建议操作：稍后重试。

后续操作¶

调用完成后，需要核对配置时查询技能详情。

最后更新于 2026 年 9 月 9 日