# 智能体 (/zh/api-reference/endpoint/agent)

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

> 你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 了解自动化入门说明。

`POST /agent`

启动用于 Agent 驱动数据提取的任务

## OpenAPI

```json
{
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": {
            "auditMetadata": {
              "additionalProperties": false,
              "description": "为组织启用 SIEM Logging 后，SIEM 日志事件中会包含用户归属信息。",
              "properties": {
                "username": {
                  "description": "与该请求关联的用户名。",
                  "maxLength": 1024,
                  "type": "string"
                }
              },
              "required": [
                "username"
              ],
              "type": "object"
            },
            "maxCredits": {
              "description": "此代理任务可使用的最大额度。若未设置，默认值为 2500。高于 2,500 的值一律按付费请求计费。",
              "type": "number"
            },
            "model": {
              "default": "spark-1-mini",
              "description": "适用于智能体任务的模型。spark-1-mini（默认）成本更低，价格便宜约 60%；spark-1-pro 在处理复杂任务时能提供更高的准确率。",
              "enum": [
                "spark-1-mini",
                "spark-1-pro"
              ],
              "type": "string"
            },
            "prompt": {
              "description": "用于描述应提取哪些数据的提示词",
              "maxLength": 10000,
              "type": "string"
            },
            "schema": {
              "description": "用于定义提取数据结构的可选 JSON Schema",
              "type": "object"
            },
            "strictConstrainToURLs": {
              "description": "如果为 true，代理将仅访问 urls 数组中提供的 URL",
              "type": "boolean"
            },
            "threatProtection": {
              "description": "此请求的[威胁防护](https://docs.firecrawl.dev/features/threat-protection)按请求覆盖配置。你提供的字段仅会替换此次请求中你所在组织策略的对应字段；未提供的字段则保留组织级配置值。你的团队必须已启用威胁防护（企业版功能），否则该请求会因 403 被拒绝。如果你的组织已禁用请求级覆盖，任何包含此对象的请求都会因 403 被拒绝。如果你的团队强制启用了威胁防护，则不得将 `mode` 设为 `off`。",
              "properties": {
                "blacklist": {
                  "description": "始终封禁的域名，可使用普通域名（`example.com`）或通配符模式（`*.example.com`）。不包含协议、路径或端口。",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "blockedTlds": {
                  "description": "直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                },
                "failurePolicy": {
                  "description": "当无法访问 classifier 时的处理方式：`closed` 会封禁该请求，`open` 则允许该请求。",
                  "enum": [
                    "open",
                    "closed"
                  ],
                  "type": "string"
                },
                "mode": {
                  "description": "此次请求的 URL 扫描模式。`normal` 使用 Google Web Risk 检查 URL（每扫描 1 个 URL 额外消耗 2 个额度）。",
                  "enum": [
                    "off",
                    "normal"
                  ],
                  "type": "string"
                },
                "riskScoreThreshold": {
                  "description": "归一化风险评分（0–100）阈值。达到或超过该值时，分类器判定会封禁该 URL。值越低，限制越严格。",
                  "example": 75,
                  "maximum": 100,
                  "minimum": 0,
                  "type": "integer"
                },
                "whitelist": {
                  "description": "始终允许的域名，可使用普通域名或通配符模式。优先级高于其他所有规则。",
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 1000,
                  "type": "array"
                }
              },
              "title": "Threat Protection Override",
              "type": "object"
            },
            "urls": {
              "description": "用于限定智能体访问范围的可选 URL 列表",
              "items": {
                "format": "uri",
                "type": "string"
              },
              "type": "array"
            }
          },
          "required": [
            "prompt"
          ],
          "type": "object"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "success": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "代理任务已成功启动"
    },
    "402": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Payment required to access this resource.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "需要付款"
    },
    "429": {
      "content": {
        "application/json": {
          "schema": {
            "properties": {
              "error": {
                "example": "Rate limit exceeded.",
                "type": "string"
              }
            },
            "type": "object"
          }
        }
      },
      "description": "请求次数过多"
    }
  }
}
```