> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建代理作业

> 创建一个新的 agent 作业，可根据提供的消息和 branch 信息生成并编辑文档。

此端点会根据提供的消息和 branch 信息创建一个代理任务。该任务异步执行，并以流式方式返回包含执行详情与结果的响应。

如果 branch 不存在，代理会自动创建该 branch。若文件编辑成功，任务结束时会自动创建一个拉取请求（PR；亦称“合并请求”/Merge Request）。

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

代理 API 的限制如下：

* 每个 Mintlify 项目每小时最多可调用 100 次

<div id="suggested-usage">
  ## 建议用法
</div>

为获得最佳效果，请使用 [ai-sdk 的 useChat 钩子](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) 来发送请求并处理响应。


## OpenAPI

````yaml zh/admin-openapi.json post /agent/{projectId}/job
openapi: 3.0.1
info:
  title: Mintlify Admin API
  description: 用于管理操作的 API，包括文档更新和代理管理。
  version: 1.0.0
servers:
  - url: https://api.mintlify.com/v1
security:
  - bearerAuth: []
paths:
  /agent/{projectId}/job:
    post:
      summary: 创建代理作业
      description: 创建一个新的 agent 作业，可根据提供的消息和 branch 信息生成并编辑文档。
      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:
                - branch
                - messages
              properties:
                branch:
                  type: string
                  description: 代理应处理的 Git branch 名称，若该 branch 不存在，将会自动创建
                messages:
                  type: array
                  description: 要提供给代理的消息列表。系统会始终在最前面自动添加一个默认的系统提示词，因此通常只需要包含用户消息即可。
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - system
                          - user
                        description: >-
                          消息发送方的角色。使用 `user` 表示任务指令。使用 `system`
                          添加补充指令，这些指令会附加在默认 system prompt 之后（不会替换默认的 system
                          prompt）。
                      content:
                        type: string
                        description: 消息内容。
                asDraft:
                  type: boolean
                  default: true
                  description: >-
                    控制是否以草稿模式或非草稿模式创建拉取请求（PR；亦称“合并请求”/Merge Request）。为 true
                    时，将创建草稿拉取请求；为 false 时，将创建常规（非草稿）拉取请求，供审核使用。
                model:
                  type: string
                  enum:
                    - sonnet
                    - opus
                  default: sonnet
                  description: >-
                    用于该智能体任务的 AI 模型。使用 `sonnet` 可获得更快捷、成本更低的处理。使用 `opus`
                    可获得更强大但速度更慢的处理。
      responses:
        '200':
          description: 代理任务已成功创建（流式响应）。X-Session-Id 头会随响应一同返回
          headers:
            X-Message-Id:
              schema:
                type: string
              description: 已创建任务的消息标识符
          content:
            text/plain:
              schema:
                type: string
                description: 包含代理任务执行详情和结果的流式响应。
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization 请求头需要使用 Bearer token。请在此处创建一个 [Admin API Key（管理员 API
        密钥）](https://dashboard.mintlify.com/settings/organization/api-keys)。

````