> ## 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 节点上的智能体、向节点部署新的智能体，以及查看集群中跨所有节点的全局智能体列表。

## 列出节点上的智能体

**GET** `/v1/gpu-nodes/:id/agents`

认证：需要 Bearer API 密钥。

### 路径参数

<ParamField path="id" type="string" required>
  GPU 节点标识符，例如 gn\_a1b2c3d4。
</ParamField>

### 响应

<ResponseField name="items" type="array" required>
  该节点的 [智能体](/api-reference/pin/agents/get) 对象数组。
</ResponseField>

### 示例

```bash theme={null}
curl -s http://<pin-host>:8001/v1/gpu-nodes/gn_a1b2c3d4/agents \
  -H "Authorization: Bearer $ARIA_PIN_KEY"
```

```json theme={null}
{
  "items": [
    {
      "id": "ag_7f8e9d0c",
      "name": "agent-gn_a1b2c3d4",
      "gpu_count": 8,
      "status": "online",
      "node_id": "gn_a1b2c3d4",
      "version": "1.2.0",
      "deploy_state": "deployed"
    }
  ]
}
```

## 向节点部署智能体

**POST** `/v1/gpu-nodes/:id/agents`

认证：需要 Bearer API 密钥。

### 路径参数

<ParamField path="id" type="string" required>
  GPU 节点标识符。
</ParamField>

### 请求体

<ParamField body="name" type="string">
  智能体名称（可选，默认为 agent-{node_id}）。
</ParamField>

### 响应

<ResponseField name="code" type="integer">
  响应码（成功为 0）。
</ResponseField>

<ResponseField name="data" type="object" required>
  所部署的 [智能体](/api-reference/pin/agents/get) 对象。
</ResponseField>

<ResponseField name="message" type="string">
  成功时为空。
</ResponseField>

### 示例

```bash theme={null}
curl -s -X POST http://<pin-host>:8001/v1/gpu-nodes/gn_a1b2c3d4/agents \
  -H "Authorization: Bearer $ARIA_PIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "training-agent"}'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "id": "ag_7f8e9d0c",
    "name": "training-agent",
    "gpu_count": 8,
    "status": "online",
    "node_id": "gn_a1b2c3d4",
    "version": "1.2.0",
    "deploy_state": "deployed"
  },
  "message": ""
}
```

## 列出全局全部智能体

**GET** `/v1/agents`

认证：需要 Bearer API 密钥。

### 响应

<ResponseField name="items" type="array" required>
  跨节点的全部 [智能体](/api-reference/pin/agents/get) 对象数组。
</ResponseField>

### 示例

```bash theme={null}
curl -s http://<pin-host>:8001/v1/agents \
  -H "Authorization: Bearer $ARIA_PIN_KEY"
```

```json theme={null}
{
  "items": [
    {
      "id": "ag_7f8e9d0c",
      "name": "training-agent",
      "gpu_count": 8,
      "status": "online",
      "node_id": "gn_a1b2c3d4",
      "version": "1.2.0",
      "deploy_state": "deployed"
    }
  ]
}
```