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

# Agent Traceを取得

各エージェント runでは、正規の**実行トレース**が記録されます。これは、呼び出したツールとその戻り値、推論の要約、進捗アップデート、ブラウザセッション、出力アーティファクトへの変更など、実行中に行われたすべての操作を記録した時系列のイベントストリームです。これは、[Agent playground](https://www.firecrawl.dev/app/agent)のライブActivityビューを支えるイベントストリームと同じものです。

<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種類のイベントバリアントを区別します。全一覧と各バリアントのフィールドについては、以下のレスポンススキーマを参照してください。

`artifact.updated` イベントにはアーティファクトのコンテンツ自体は含まれません。`snapshotId` によって参照されるため、[snapshot endpoint](/ja/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 ja/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のサービスを利用して、Webスクレイピングやクロールを行うための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
                      イベントには、snapshots エンドポイントで使用する 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

````