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

# 节点智能体心跳

> GPU 节点智能体向 PIN 控制器上报存活状态与刷新后的 GPU 清单。

发送周期心跳，使 PIN 控制器得知智能体处于健康状态。心跳会更新最近一次可见时间戳与 GPU 清单。若智能体超过心跳超时仍未出现，控制器会回收并重新入队任何已分配的任务。

<Warning>
  节点智能体接口使用部署时引导的 agent 注册令牌。请将其作为 `Authorization: Bearer <agent-token>` 传递。
</Warning>

## 接口

**POST** `/v1/agent/heartbeat`

认证：`Authorization: Bearer <agent-token>`

## 请求体

<ParamField body="agent_id" type="string" required>
  注册时返回的稳定 agent ID。
</ParamField>

<ParamField body="gpus" type="array">
  当前 GPU 清单快照。
</ParamField>

<ParamField body="status" type="string">
  智能体状态，例如 `online`。
</ParamField>

<ParamField body="version" type="string">
  智能体二进制版本。
</ParamField>

## 响应

<ResponseField name="ok" type="boolean">
  心跳是否被接受。
</ResponseField>

## 示例

```bash theme={null}
curl -X POST http://<pin-host>:8001/v1/agent/heartbeat \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ag_1234567890",
    "gpus": [
      {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":10.0,"slots":1,"used_slots":1}
    ],
    "status": "online",
    "version": "1.2.0"
  }'
```

```json theme={null}
{
  "ok": true
}
```