# 创建 Agent 作业 (/zh/api/agent/v2/create-agent-job)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1059 · updated: 2026-07-30 -->

此端点用于创建后台 Agent 作业。该作业会异步运行。请使用 [获取 Agent 作业](/zh/api/agent/v2/get-agent-job) 端点轮询状态更新。

如果 Agent 成功编辑文件，则会自动创建拉取请求 (PR；亦称“合并请求”/Merge Request) ，并在作业响应中填充 `prLink` 字段。

<div id="rate-limits">
  ## 速率限制 [#速率限制]
</div>

* 每个 Mintlify 项目每小时可使用 100 次

<div id="usage">
  ## 用法 [#用法]
</div>

```bash
curl -X POST https://api.mintlify.com/v2/agent/{projectId}/job \
  -H "Authorization: Bearer mint_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Add a quickstart guide for the Python SDK"}'
```

`POST /v2/agent/{projectId}/job`

创建一个在后台运行的新代理作业。该作业会异步处理提示词——轮询 get job 端点以跟踪进度。如果代理成功编辑文件，则会自动创建拉取请求（PR；亦称“合并请求”/Merge Request）。

使用管理员 API 密钥进行身份验证。

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "projectId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "你的项目 ID。可从你的控制台中的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面复制。"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "prompt"
          ],
          "properties": {
            "prompt": {
              "type": "string",
              "minLength": 1,
              "description": "供代理执行的指令。"
            }
          }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "代理作业创建成功",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "代理任务的唯一标识符。"
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "completed",
                  "archived",
                  "failed"
                ],
                "description": "作业的当前状态。`active`——代理当前正在处理提示词。`completed`——代理已成功完成，并且可能已创建 PR（请检查 `prLink`）。`archived`——作业已归档。`failed`——代理遇到了不可恢复的错误。请持续轮询，直到状态变为 `completed`、`archived` 或 `failed`。"
              },
              "source": {
                "type": "object",
                "description": "源存储库信息。",
                "properties": {
                  "repository": {
                    "type": "string",
                    "description": "GitHub 存储库的完整 URL。"
                  },
                  "ref": {
                    "type": "string",
                    "description": "代理正在处理的 Git branch。",
                    "nullable": true
                  }
                }
              },
              "model": {
                "type": "string",
                "description": "此作业使用的 AI 模型。"
              },
              "prLink": {
                "type": "string",
                "format": "uri",
                "example": "https://github.com/org/repo/pull/123",
                "description": "由代理创建的 GitHub 拉取请求（PR；亦称“合并请求”/Merge Request）URL。作业仍处于 `active` 状态或没有文件变更时，该值为 `null`。代理成功创建 PR 后，此字段会被填充。",
                "nullable": true
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "作业创建时的时间戳。"
              },
              "archivedAt": {
                "type": "string",
                "format": "date-time",
                "description": "作业归档时的时间戳。",
                "nullable": true
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "无效请求",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          }
        }
      }
    },
    "429": {
      "description": "超出速率限制",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "错误消息。"
              }
            }
          }
        }
      }
    }
  }
}
```