> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取代理执行追踪

每次代理运行都会记录一份规范的**执行追踪**：按顺序记录本次运行所执行的所有操作，包括调用的工具及其返回结果、推理摘要、进度更新、浏览器会话，以及输出产物的变更。这与 [Agent playground](https://www.firecrawl.dev/app/agent) 中实时活动视图使用的是同一事件流。

<div id="what-its-for">
  ## 用途
</div>

* **调试运行** — 查看代理执行的具体搜索、抓取和提取操作、各工具的输入 (`tool_call.started`) 和结果 (`tool_call.finished`) ，以及运行在哪一步出错 (`error.occurred`，还有最终 `run.finished` 事件的 `outcome` 和结构化 `error`) 。
* **实时进度 UI** — 在任务处于 `processing` 状态时轮询执行追踪，实时展示代理正在执行的操作。`progress.reported` 事件包含运行阶段 (`planning`、`working`、`finalizing`) 及易于理解的消息，`reasoning.summary` 事件则会呈现代理的思考过程。
* **实时浏览器视图** — 运行期间传入 `?liveView=true`，即可获取 `activeBrowserSessions`：该运行的活跃浏览器会话。每个会话都提供可嵌入的 `liveViewUrl`，可用于观看 (或演示) 代理浏览网页的过程。
* **成本跟踪** — `creditsUsed` 会报告截至目前已消耗的额度；如果设置了运行的 `maxCredits`，消耗额度不会超过该上限。

<div id="how-it-works">
  ## 工作原理
</div>

事件由运行中的代理 (`orchestrator` 及其 `subagent`) 发出，每个事件都会在 `agent` 字段中标识发出者。浏览器操作在代理自己的浏览器会话中进行，并通过 `browser.session.*` 事件上报，而非由独立的浏览器代理执行。请按 `producerSequence` (每个事件发出代理各自的序列) 对事件排序。`type` 字段用于区分 13 种事件变体；完整列表及各变体的字段请参见下方的响应 schema。

`artifact.updated` 事件本身不包含输出产物内容，而是通过 `snapshotId` 引用该内容；您可通过 [snapshot endpoint](/zh/api-reference/endpoint/agent-snapshot) 获取。

在收到 `run.finished` 后，事件可能还会继续到达一小段时间。因此，如果您正在轮询实时运行，请在渲染最终状态前保留一个短暂的收尾窗口。

<Note>Spark 2 运行会记录执行追踪，也就是所有新的运行。Spark 1 模型退役前启动的任务不含执行追踪，并会返回 `400`。</Note>

> 您是需要 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 GET /agent/{jobId}/trace
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/{jobId}/trace:
    parameters:
      - description: 代理任务的 ID
        in: path
        name: jobId
        required: true
        schema:
          format: uuid
          type: string
    get:
      tags:
        - Agent
      summary: 获取代理任务的执行追踪
      operationId: getAgentTrace
      parameters:
        - description: 如果为 "true"，则包含带有实时视图 URL 的当前活跃浏览器会话。
          in: query
          name: liveView
          required: false
          schema:
            enum:
              - 'true'
              - 'false'
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  activeBrowserSessions:
                    description: 当前活跃的浏览器会话（仅当 liveView=true 时提供）。
                    items:
                      properties:
                        id:
                          type: string
                        liveViewUrl:
                          type: string
                        viewport:
                          properties:
                            height:
                              type: number
                            width:
                              type: number
                          type: object
                      type: object
                    type: array
                  creditsUsed:
                    description: 截至目前已消耗的额度；如果设置了 maxCredits，则以该值为上限。
                    type: number
                  events:
                    description: >-
                      运行的规范执行事件；按 producerSequence 排序。artifact.updated
                      事件包含快照端点使用的 snapshotId 值。
                    items:
                      $ref: '#/components/schemas/AgentTraceEvent'
                    type: array
                  id:
                    format: uuid
                    type: string
                  success:
                    type: boolean
                type: object
          description: 成功响应
        '400':
          content:
            application/json:
              schema:
                properties:
                  error:
                    example: Trace is only available for Spark 2 extracts
                    type: string
                type: object
          description: 请求错误 — 任务 ID 不是有效的 UUID，或任务并非在 spark-2 上运行（追踪信息仅适用于 spark-2 代理任务）。
        '404':
          content:
            application/json:
              schema:
                properties:
                  error:
                    example: Agent job not found
                    type: string
                type: object
          description: 未找到代理任务
      security:
        - bearerAuth: []
components:
  schemas:
    AgentTraceEvent:
      description: >-
        代理运行产生的规范执行事件。每个事件都包含封装字段
        schemaVersion、eventId、runId、occurredAt、producerSequence 和 agent；type
        字段用于区分变体。usage.recorded 事件为内部事件，绝不会公开；agent.started 事件不包含 model 字段。
      discriminator:
        propertyName: type
      oneOf:
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 运行开始时发出。
              enum:
                - run.started
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
          title: run.started
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            reason:
              enum:
                - user
              type: string
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 请求取消时发出（通过 DELETE /agent/{jobId}）。
              enum:
                - run.cancel_requested
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - reason
          title: run.cancel_requested
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            error:
              allOf:
                - $ref: '#/components/schemas/AgentTraceError'
              description: 当 outcome 为 succeeded 时为 null；否则为结构化错误。
              nullable: true
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            outcome:
              enum:
                - succeeded
                - failed
                - cancelled
                - refused
                - credit_limit_reached
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 运行的终止事件。
              enum:
                - run.finished
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - outcome
            - error
          title: run.finished
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 代理（编排器或子代理）启动时发出。
              enum:
                - agent.started
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
          title: agent.started
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            durationMs:
              type: integer
            error:
              allOf:
                - $ref: '#/components/schemas/AgentTraceError'
              description: 当 outcome 为 succeeded 时为 null；否则为结构化错误。
              nullable: true
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            outcome:
              enum:
                - succeeded
                - failed
                - cancelled
                - refused
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 代理完成时发出。
              enum:
                - agent.finished
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - outcome
            - durationMs
            - error
          title: agent.finished
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            sessionId:
              type: string
            type:
              description: 浏览器会话启动时发出。
              enum:
                - browser.session.started
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - sessionId
          title: browser.session.started
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            durationMs:
              type: integer
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            sessionId:
              type: string
            type:
              description: 浏览器会话结束时发出。
              enum:
                - browser.session.finished
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - sessionId
            - durationMs
          title: browser.session.finished
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            message:
              type: string
            occurredAt:
              format: date-time
              type: string
            phase:
              enum:
                - planning
                - working
                - finalizing
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 编排器报告进度时发出。
              enum:
                - progress.reported
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - phase
            - message
          title: progress.reported
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            text:
              type: string
            type:
              description: 代理推理过程的摘要。
              enum:
                - reasoning.summary
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - text
          title: reasoning.summary
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            parameters:
              description: 传给工具的输入（任意 JSON）。
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            toolCallId:
              type: string
            toolName:
              type: string
            type:
              description: 工具调用开始时发出。
              enum:
                - tool_call.started
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - toolCallId
            - toolName
            - parameters
          title: tool_call.started
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            result:
              description: 工具返回的结果（任意 JSON）。
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            toolCallId:
              type: string
            toolName:
              type: string
            type:
              description: 工具调用完成时发出。
              enum:
                - tool_call.finished
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - toolCallId
            - toolName
            - result
          title: tool_call.finished
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            artifact:
              $ref: '#/components/schemas/AgentTraceArtifact'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 输出工件变更时发出。
              enum:
                - artifact.updated
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - artifact
          title: artifact.updated
          type: object
        - properties:
            agent:
              $ref: '#/components/schemas/AgentTraceAgent'
            error:
              $ref: '#/components/schemas/AgentTraceError'
            eventId:
              description: 此事件的唯一 ID。
              format: uuid
              type: string
            occurredAt:
              format: date-time
              type: string
            producerSequence:
              description: 发出事件的代理生成的单调递增序列号；请据此对事件排序。
              type: integer
            runId:
              description: 此事件所属的代理任务 ID。
              format: uuid
              type: string
            schemaVersion:
              enum:
                - 1
              type: integer
            type:
              description: 运行期间发生非致命错误时发出。
              enum:
                - error.occurred
              type: string
          required:
            - schemaVersion
            - eventId
            - runId
            - occurredAt
            - producerSequence
            - agent
            - type
            - error
          title: error.occurred
          type: object
    AgentTraceAgent:
      description: 发出该事件的代理的标识。
      properties:
        id:
          format: uuid
          type: string
        name:
          type: string
        parentId:
          description: 父代理的 ID（仅子代理提供）。
          format: uuid
          type: string
        role:
          enum:
            - orchestrator
            - subagent
            - system
          type: string
      required:
        - id
        - role
        - name
      type: object
    AgentTraceError:
      description: 附加到终止事件和错误事件的结构化错误。
      properties:
        code:
          enum:
            - cancelled
            - credit_limit_reached
            - parent_finished
            - refused
            - internal
          type: string
        message:
          type: string
        retryable:
          type: boolean
        source:
          enum:
            - agent
            - tool
            - billing
            - system
          type: string
      required:
        - code
        - source
        - retryable
        - message
      type: object
    AgentTraceArtifact:
      description: 输出工件变更的描述信息。
      properties:
        artifactId:
          type: string
        change:
          enum:
            - init
            - partial
            - append
            - modify
            - update
          type: string
        changedFields:
          items:
            type: string
          type: array
        itemCount:
          type: integer
        kind:
          enum:
            - json
            - markdown
            - html
            - screenshot
            - text
          type: string
        path:
          description: 工件的工作区路径，例如 /workspace/data.json。
          type: string
        snapshotId:
          description: 传入 GET /agent/{jobId}/snapshots/{snapshotId} 以获取此快照的内容。
          format: uuid
          type: string
        sourceToolCallId:
          description: 产生此变更的工具调用（如适用）。
          type: string
      required:
        - kind
        - artifactId
        - snapshotId
        - change
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````