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

# 为节点智能体获取下一个待处理任务

> 节点智能体长轮询此接口，以获取 PIN 控制平面分配给它们的下一个待处理训练任务。

节点智能体调用此接口来获取下一个待处理任务。控制器采用长轮询：当存在匹配的任务时立即返回，否则在有界等待后返回 `204 No Content`，以便智能体重试。

<Warning>
  此接口由节点智能体调用，而非终端用户。它需要智能体注册时签发的 `X-Agent-Secret` 头。
</Warning>

## 接口

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

## 认证

`X-Agent-Secret: <agent_secret>`。

## 请求体

<ParamField body="agent_id" type="string" required>
  [注册](/api-reference/pin/node-agent/register) 返回的稳定 agent 标识符。
</ParamField>

<ParamField body="capabilities" type="object">
  当前能力快照，包括空闲 GPU 索引与显存。
</ParamField>

## 响应

无可用任务时返回 `204 No Content`。匹配时返回带有任务负载的 PIN 信封。

<ResponseField name="code" type="integer">
  匹配时为 `0`。
</ResponseField>

<ResponseField name="data" type="object">
  完整任务负载：`job_id`、`type`、`base_model`、`dataset_id`、`lora`、`hyperparams`、`assigned_gpu_index`。
</ResponseField>

## 示例

```bash theme={null}
curl -X POST https://ariapin.example.com/v1/agent/acquire \
  -H "X-Agent-Secret: $AGENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "ag_01", "capabilities": {"free_gpus": [0, 1]}}'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "job_0198a...",
    "type": "sft",
    "base_model": "meta-llama/Llama-3-8B",
    "assigned_gpu_index": 0
  },
  "message": ""
}
```