> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-capy-docs-factual-copy-fixes.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 智能体 > 你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 了解自动化入门说明。 ## OpenAPI ````yaml zh/api-reference/v2-openapi.json POST /agent openapi: 3.0.0 info: contact: email: support@firecrawl.dev name: Firecrawl Support url: https://firecrawl.dev/support description: 用于与 Firecrawl 服务交互，执行网页抓取和爬取任务的 API。 title: Firecrawl API version: v2 servers: - url: https://api.firecrawl.dev/v2 security: - bearerAuth: [] paths: /agent: post: tags: - Agent summary: 启动用于 Agent 驱动数据提取的任务 operationId: startAgent requestBody: content: application/json: schema: properties: auditMetadata: $ref: '#/components/schemas/AuditMetadata' effort: description: 代理任务的推理预算。每次运行均在 spark-2 上执行，因此无论是否指定模型，都可以传入 effort。 enum: - low - medium - high type: string exchange: additionalProperties: false description: >- 允许代理在运行期间调用您团队的 [Alexandria](https://docs.firecrawl.dev/features/alexandria) 数据提供商。不提供此 object 时，运行仅使用网页数据（后续轮次会沿用上一轮的设置）。请参见 [使用已连接的 Alexandria 工具](https://docs.firecrawl.dev/features/agent#use-your-connected-alexandria-tools)。 properties: approve: additionalProperties: false description: 批准此会话上一轮结束时返回的 `pendingApproval`。需要 `threadId`。 properties: always: default: false description: 在会话的剩余轮次中不再请求审批。对于 `terms` 审批，此项会被忽略。 type: boolean approvalId: description: 要回应的 `pendingApproval.id`。 format: uuid type: string callIds: description: 仅执行审批请求中的这些调用。默认执行全部调用。对于 `terms` 审批，此项会被忽略。 items: type: string type: array required: - approvalId type: object decline: additionalProperties: false description: >- 拒绝此会话上一轮结束时返回的 `pendingApproval`。需要 `threadId`。拒绝 `terms` 提议后，会话的剩余轮次将不再使用相关提供商。 properties: approvalId: description: 要回应的 `pendingApproval.id`。 format: uuid type: string required: - approvalId type: object enabled: default: true description: >- 允许代理调用 Alexandria 提供商。传入 `exchange` 时，默认值为 `true`；传入 `false` 可在会话的某一轮禁用提供商。 type: boolean maxCalls: default: 16 description: 代理在本轮中调用提供商的次数上限。 maximum: 30 minimum: 1 type: integer onTermsRequired: default: skip description: >- 当代理拟使用的提供商要求接受数据条款，而您的团队尚未接受时的处理方式。此类提供商不会被调用。`skip` 使用已接受条款的提供商作答，并在 `exchange.skippedProviders` 中列出其他提供商；`ask` 还会在结束本轮时返回类型为 `terms` 的 `pendingApproval` 和 `exchange.requiresAction`。在后续轮次中省略此项会沿用上一轮的值。请参见 [需要接受条款的数据提供商](https://docs.firecrawl.dev/features/agent#data-providers-that-need-terms)。 enum: - skip - ask type: string requireApproval: default: false description: >- 在调用任何付费提供商之前，结束本轮并返回类型为 `calls` 的 `pendingApproval`，由您在下一轮批准或拒绝。必须在同一请求中设置 `mode: "chat"`，后续请求也不例外。 type: boolean toolkits: description: >- 通过 slug 指定最多 5 个提供商，例如 `["apollo"]`。代理将仅使用这些提供商。留空或省略表示使用您的团队可用的所有提供商。 items: type: string maxItems: 5 type: array type: object maxCredits: description: 此代理任务可使用的最大额度。若未设置，默认值为 2500。高于 2,500 的值一律按付费请求计费。 type: number mode: default: extract description: >- `extract` 每轮都会在 `data` 中返回完整的结构化结果。使用 `chat` 时，不请求新数据的后续请求会在 `message` 中获得简短回复，而不会重新运行。使用 `exchange.requireApproval` 时，必须在同一请求中使用 `chat`。在后续轮次中省略此项会沿用会话的模式。 enum: - extract - chat type: string model: default: spark-2 description: >- 适用于代理任务的模型。spark-2 是默认值，也是每次运行所执行的模型。出于向后兼容性考虑，仍接受 Spark 1 模型名称，但已弃用，并会路由到 spark-2。 enum: - spark-2 - 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 threadId: description: >- 继续现有会话：传入先前运行返回的 `threadId`，此请求将作为该会话的下一轮运行。未指定的 `urls`、`schema`、`effort`、`mode` 和 `exchange` 设置会沿用上一轮的设置。省略 `threadId` 可开始新会话。 format: uuid type: string threatProtection: $ref: '#/components/schemas/ThreatProtectionOverride' urls: description: 用于限定智能体访问范围的可选 URL 列表 items: format: uri type: string type: array webhook: description: >- Webhook 规范对象。订阅代理生命周期事件（agent.started、agent.action、agent.completed、agent.failed、agent.cancelled）。 properties: events: default: - started - action - completed - failed - cancelled description: 发送到 webhook URL 的事件。默认值为所有事件。 items: enum: - started - action - completed - failed - cancelled type: string type: array headers: additionalProperties: type: string description: 发送到 webhook URL 的请求头。 type: object metadata: additionalProperties: type: string description: 将包含在此代理任务所有 webhook 负载中的自定义元数据。 type: object url: description: 用于接收 webhook 事件的 URL。 format: uri type: string required: - url type: object required: - prompt type: object required: true responses: '200': content: application/json: schema: properties: id: format: uuid type: string success: type: boolean threadId: description: 本次运行所属的会话。将其作为 `threadId` 传入以继续会话。 format: uuid type: string threadTurn: description: 本次运行在会话中的轮次，从 1 开始。 type: integer type: object description: 代理任务已成功启动 '400': content: application/json: schema: properties: error: example: 'Invalid JSON schema: ...' type: string type: object description: 请求错误 — 请求正文未通过验证（例如 JSON schema 无效）。 '402': content: application/json: schema: properties: error: example: Payment required to access this resource. type: string type: object description: 需要付款 '403': content: application/json: schema: properties: error: example: >- This URL (https://example.com) is blocked by your organization's threat protection policy (rule: blocklist). If you believe this is a mistake, contact your organization administrator to adjust the policy (e.g. whitelist the domain). type: string type: object description: 禁止访问 — 提供的 URL 被团队的威胁防护策略封禁。 '429': content: application/json: schema: properties: error: example: Rate limit exceeded. type: string type: object description: 请求次数过多 '500': content: application/json: schema: properties: error: example: Failed to passthrough agent request. type: string type: object description: 内部服务器错误 — 无法访问代理服务。 security: - bearerAuth: [] components: schemas: AuditMetadata: additionalProperties: false description: 为组织启用 SIEM Logging 后，SIEM 日志事件中会包含用户归属信息。 properties: username: description: 与该请求关联的用户名。 maxLength: 1024 type: string required: - username type: object ThreatProtectionOverride: 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 securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.