> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 节点智能体控制通道与干预

> 通过控制通道向 PIN 节点智能体下发生命周期与干预命令，并接收命令回执。

控制通道承载从 PIN 控制平面到节点智能体的生命周期与干预命令，并返回回执。终端用户调用面向用户的控制接口；智能体轮询待处理控制队列，并对处理的每条命令进行确认。

<Warning>
  智能体侧接口需要 `X-Agent-Secret`。面向用户的控制接口使用 `Authorization: Bearer <api_key or JWT>`。
</Warning>

## 发送控制命令

```http theme={null}
POST /v1/agent/jobs/{id}/control
```

`Authorization: Bearer <api_key or JWT>`。为被分配的智能体入队一条命令。

<ParamField body="action" type="string" required>
  取值之一：`run`、`stop`、`resume`、`delete`。
</ParamField>

返回 `{"status": "queued"}`。

## 轮询待处理命令

```http theme={null}
GET /v1/agent/jobs/pending-control?agent_id={agent_id}
```

`X-Agent-Secret`。返回 `{ "commands": [{ "id": "cmd_...", "action": "stop", "job_id": "..." }] }`。

## 确认命令

```http theme={null}
POST /v1/agent/jobs/{id}/control/{cmdId}/ack
```

`X-Agent-Secret`。

<ParamField body="result" type="string">
  自由格式的结果摘要。
</ParamField>

<ParamField body="failed" type="boolean">
  若智能体无法执行该命令则为 `true`。
</ParamField>

返回 `{"ok": true}`。

## 应用干预

```http theme={null}
POST /v1/agent/intervention/apply
```

`X-Agent-Secret`。上报某条干预已在训练 worker 上被应用。

<ParamField body="intervention_id" type="string" required>
  由 [干预](/api-reference/pin/jobs/intervene) 分配的干预标识符。
</ParamField>

<ParamField body="applied_at" type="string">
  应用的 RFC 3339 时间戳。
</ParamField>

## 列出某任务的干预

```http theme={null}
GET /v1/agent/interventions/{jobId}
```

`X-Agent-Secret`。返回智能体必须为该任务应用的干预。

## 获取任务负载

```http theme={null}
GET /v1/agent/jobs/{id}
```

`X-Agent-Secret`。返回已分配任务的完整任务负载，供重启后重新连接的智能体使用。

## 示例

```bash theme={null}
curl -X POST https://ariapin.example.com/v1/agent/jobs/job_0198a/control \
  -H "Authorization: Bearer $ARIAPIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "stop"}'
```

```json theme={null}
{
  "code": 0,
  "data": { "status": "queued" },
  "message": ""
}
```