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

# List and Deploy Node Agents

> List agents on a GPU node or deploy a new agent, plus view the global agent list across all nodes in Aria Compute PIN.

This page covers three endpoints: listing agents on a specific GPU node, deploying a new agent to a node, and viewing the global agent list across the cluster.

## List agents on a node

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

Authorization: Bearer API key required.

### Path parameters

<ParamField path="id" type="string" required>
  GPU node identifier, e.g. gn\_a1b2c3d4.
</ParamField>

### Response

<ResponseField name="items" type="array" required>
  Array of [Agent](/api-reference/pin/agents/get) objects for this node.
</ResponseField>

### Example

```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"
    }
  ]
}
```

## Deploy an agent to a node

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

Authorization: Bearer API key required.

### Path parameters

<ParamField path="id" type="string" required>
  GPU node identifier.
</ParamField>

### Request body

<ParamField body="name" type="string">
  Agent name (optional, defaults to agent-{node_id}).
</ParamField>

### Response

<ResponseField name="code" type="integer">
  Response code (0 for success).
</ResponseField>

<ResponseField name="data" type="object" required>
  The deployed [Agent](/api-reference/pin/agents/get) object.
</ResponseField>

<ResponseField name="message" type="string">
  Empty on success.
</ResponseField>

### Example

```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": ""
}
```

## List all agents globally

**GET** `/v1/agents`

Authorization: Bearer API key required.

### Response

<ResponseField name="items" type="array" required>
  Array of all [Agent](/api-reference/pin/agents/get) objects across nodes.
</ResponseField>

### Example

```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"
    }
  ]
}
```


## Related topics

- [List GPU Nodes](/api-reference/pin/gpu-nodes/list.md)
- [Node Agent Control Channel and Interventions](/api-reference/pin/node-agent/control.md)
- [Node Agent Register](/api-reference/pin/node-agent/register.md)
- [Node Agent Heartbeat](/api-reference/pin/node-agent/heartbeat.md)
- [List Agent Turns](/api-reference/agent/turns/list.md)