# 执行技能

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

```text
POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/skills/{skill_id}/execute
```

## 调用前准备

先[查询技能详情](get-skill.md)确认技能为活动状态。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和技能 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：执行工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$SKILL_ID`：要执行的技能 ID。

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

## 路径参数

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

## 查询参数

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

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `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 | 否 | 扩展元数据。变量、参数、输入片段和元数据中不能包含密钥或运行会话引用。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/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>"
  }'
```

## 成功响应

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

```json
{
  "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"
  }
}
```

响应字段如下。

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

## 错误响应

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

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

## 后续操作

调用完成后，需要核对配置时[查询技能详情](get-skill.md)。