> ## 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 清单与标签。

GPU 节点智能体在启动时调用此接口向咏唱引擎 PIN 控制器注册。成功后，控制器返回包含稳定 agent ID 的智能体记录。智能体必须在后续请求中携带其注册令牌。

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

## 接口

**POST** `/v1/agent/register`

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

## 请求体

<ParamField body="id" type="string">
  可选的稳定 agent ID（例如由 systemd 注入的 `ARIA_AGENT_ID`）。若与已有的预创建行匹配，控制器会更新该记录。
</ParamField>

<ParamField body="name" type="string" required>
  此智能体的主机名或显示名称。
</ParamField>

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

<ParamField body="gpus" type="array">
  GPU 清单对象列表。

  <Expandable>
    <ResponseField name="index" type="integer">
      GPU 设备索引。
    </ResponseField>

    <ResponseField name="model" type="string">
      GPU 型号名称。
    </ResponseField>

    <ResponseField name="mem_total_gb" type="number">
      GPU 总显存，以 GB 为单位。
    </ResponseField>

    <ResponseField name="mem_used_gb" type="number">
      当前已用 GPU 显存，以 GB 为单位。
    </ResponseField>

    <ResponseField name="slots" type="integer">
      此 GPU 的总槽位数。
    </ResponseField>

    <ResponseField name="used_slots" type="integer">
      当前已用槽位数。
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="labels" type="array">
  可选的字符串标签列表，用于调度。
</ParamField>

## 响应

<ResponseField name="id" type="string">
  分配的 agent ID。
</ResponseField>

<ResponseField name="name" type="string">
  智能体显示名称。
</ResponseField>

<ResponseField name="gpu_count" type="integer">
  上报的 GPU 总数。
</ResponseField>

<ResponseField name="gpus" type="array">
  回显的 GPU 清单。
</ResponseField>

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

## 示例

```bash theme={null}
curl -X POST http://<pin-host>:8001/v1/agent/register \
  -H "Authorization: Bearer <agent-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "gpu-node-01",
    "version": "1.2.0",
    "gpus": [
      {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":0.0,"slots":1,"used_slots":0}
    ],
    "labels": ["production"]
  }'
```

```json theme={null}
{
  "id": "ag_1234567890",
  "name": "gpu-node-01",
  "gpu_count": 1,
  "gpus": [
    {"index":0,"model":"A100","mem_total_gb":80.0,"mem_used_gb":0.0,"slots":1,"used_slots":0}
  ],
  "status": "online"
}
```