> ## 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.

# 上报训练指标与状态 - 节点智能体

> 节点智能体使用 agent secret 向 PIN 控制平面推送其所属任务的逐步训练指标与状态转换。

节点智能体向 PIN 控制平面推送训练遥测数据与状态转换。两个接口涵盖此功能：`/v1/agent/metrics` 用于逐步数值指标，`/v1/agent/status` 用于任务状态转换。

<Warning>
  两个接口都需要 `X-Agent-Secret`。它们面向节点智能体，而非终端用户。
</Warning>

## 推送指标

```http theme={null}
POST /v1/agent/metrics
```

### 请求体

<ParamField body="agent_id" type="string" required>
  发送方智能体标识符。
</ParamField>

<ParamField body="job_id" type="string" required>
  指标所属的任务。
</ParamField>

<ParamField body="step" type="integer" required>
  训练步索引。
</ParamField>

<ParamField body="loss" type="number">
  训练 loss。
</ParamField>

<ParamField body="reward" type="number">
  奖励（RL 任务）。
</ParamField>

<ParamField body="throughput" type="number">
  每秒令牌数。
</ParamField>

<ParamField body="gpu_util" type="number">
  GPU 利用率百分比。
</ParamField>

## 推送状态

```http theme={null}
POST /v1/agent/status
```

### 请求体

<ParamField body="agent_id" type="string" required>
  发送方智能体标识符。
</ParamField>

<ParamField body="job_id" type="string" required>
  任务标识符。
</ParamField>

<ParamField body="status" type="string" required>
  新状态：`running`、`paused`、`completed`、`failed`。
</ParamField>

<ParamField body="error" type="string">
  当 `status = failed` 时的错误消息。
</ParamField>

## 响应

两个接口成功时均返回 `{"code": 0, "data": {"ok": true}, "message": ""}`。

## 示例

```bash theme={null}
curl -X POST https://ariapin.example.com/v1/agent/metrics \
  -H "X-Agent-Secret: $AGENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"ag_01","job_id":"job_0198a","step":250,"loss":0.42,"throughput":1850,"gpu_util":92}'
```