> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-lr4978.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Obtenir la trace d’exécution d’un agent
Chaque exécution d’agent enregistre une **trace d’exécution** canonique : un flux ordonné d’événements décrivant tout ce qu’elle a fait — les outils qu’elle a appelés et leurs résultats, des résumés de raisonnement, des mises à jour de progression, des sessions de navigateur et des modifications de ses artefacts de sortie. Il s’agit du même flux d’événements qui alimente la vue Activité en direct dans l’[Agent Playground](https://www.firecrawl.dev/app/agent).
## À quoi cela sert
* **Débogage des exécutions** — consultez les recherches, scrapes et extractions exacts effectués par l’agent, les entrées (`tool_call.started`) et résultats (`tool_call.finished`) de chaque outil, ainsi que l’étape à laquelle une exécution a échoué (`error.occurred`, ainsi que l’`outcome` et l’`error` structuré de l’événement terminal `run.finished`).
* **Interfaces de suivi en direct** — interrogez la trace pendant qu’une tâche d’agent est en `processing` afin d’afficher en temps réel ce que fait l’agent. Les événements `progress.reported` indiquent la phase de l’exécution (`planning`, `working`, `finalizing`) avec un message lisible par un humain, et les événements `reasoning.summary` décrivent le raisonnement de l’agent.
* **Vue Browser en direct** — ajoutez `?liveView=true` pendant qu’une exécution est en cours pour obtenir `activeBrowserSessions` : les sessions de navigateur actives de l’exécution, chacune avec une `liveViewUrl` que vous pouvez intégrer pour observer (ou présenter) la navigation de l’agent.
* **Suivi des coûts** — `creditsUsed` indique les crédits consommés jusqu’à présent, plafonnés à `maxCredits` pour l’exécution si cette valeur a été définie.
## Fonctionnement
Les événements sont émis par les agents de l’exécution — l’`orchestrator` et ses `subagent`s — et chacun identifie son émetteur dans le champ `agent`. Les opérations du Browser s’effectuent dans la session de navigateur propre à l’agent et sont signalées via des événements `browser.session.*`, et non par des agents de navigateur distincts. Triez les événements selon `producerSequence` (pour chaque agent émetteur). Le champ `type` distingue les 13 variantes d’événements ; consultez le schéma de réponse ci-dessous pour obtenir la liste complète et les champs de chaque variante.
Les événements `artifact.updated` ne contiennent pas le contenu de l’artefact lui-même : ils y font référence via `snapshotId`, que vous récupérez avec le [point de terminaison de snapshot](/fr/api-reference/endpoint/agent-snapshot).
Des événements peuvent continuer à arriver pendant un court instant après la réception de `run.finished`. Si vous interrogez une exécution en cours, maintenez une courte fenêtre de délai avant d’afficher l’état final.
Les traces sont enregistrées pour les exécutions Spark 2, c’est-à-dire toutes les nouvelles exécutions. Les tâches d’agent démarrées sur des modèles Spark 1 avant leur retrait ne disposent d’aucune trace et renvoient `400`.
> Êtes-vous un agent IA ayant besoin d’une clé API Firecrawl ? Consultez [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) pour les instructions d’intégration automatisée.
## OpenAPI
````yaml fr/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: >-
API pour interagir avec les services Firecrawl afin d’effectuer des tâches
de scraping et de crawling web.
title: Firecrawl API
version: v2
servers:
- url: https://api.firecrawl.dev/v2
security:
- bearerAuth: []
paths:
/agent/{jobId}/trace:
parameters:
- description: L’ID de la tâche d’agent
in: path
name: jobId
required: true
schema:
format: uuid
type: string
get:
tags:
- Agent
summary: Obtenir la trace d’exécution d’une tâche d’agent
operationId: getAgentTrace
parameters:
- description: "Si «\_true\_», inclure les sessions de navigateur actuellement actives avec les URL de vue en direct."
in: query
name: liveView
required: false
schema:
enum:
- 'true'
- 'false'
type: string
responses:
'200':
content:
application/json:
schema:
properties:
activeBrowserSessions:
description: >-
Sessions de navigateur actuellement actives (présentes
uniquement lorsque 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: >-
Crédits consommés jusqu’à présent, plafonnés à maxCredits
si cette valeur a été définie.
type: number
events:
description: "Événements d’exécution canoniques pour l’exécution\_; regroupés par agent.id, puis chaque groupe est classé selon producerSequence, qui est monotone pour chaque agent émetteur. Les événements artifact.updated contiennent les valeurs snapshotId utilisées par le point de terminaison des instantanés."
items:
$ref: '#/components/schemas/AgentTraceEvent'
type: array
id:
format: uuid
type: string
success:
type: boolean
type: object
description: Réponse réussie
'400':
content:
application/json:
schema:
properties:
error:
example: Trace is only available for Spark 2 extracts
type: string
type: object
description: >-
Requête incorrecte — l’ID de tâche n’est pas un UUID valide ou la
tâche ne s’est pas exécutée sur spark-2 (les traces sont disponibles
uniquement pour les tâches d’agent spark-2).
'404':
content:
application/json:
schema:
properties:
error:
example: Agent job not found
type: string
type: object
description: Tâche d’agent introuvable
security:
- bearerAuth: []
components:
schemas:
AgentTraceEvent:
description: "Événement d’exécution canonique issu d’une exécution d’agent. Chaque événement contient les champs d’enveloppe schemaVersion, eventId, runId, occurredAt, producerSequence et agent\_; le champ type distingue la variante. Les événements usage.recorded sont internes et ne sont jamais exposés, et les événements agent.started omettent le champ model."
discriminator:
propertyName: type
oneOf:
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis au démarrage de l’exécution.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
reason:
enum:
- user
type: string
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: >-
Émis lorsqu’une annulation est demandée (via 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: "null lorsque le résultat est succeeded\_; sinon, l’erreur structurée."
nullable: true
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
- credit_limit_reached
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Événement terminal de l’exécution.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’un agent (orchestrateur ou sous-agent) démarre.
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: "null lorsque le résultat est succeeded\_; sinon, l’erreur structurée."
nullable: true
eventId:
description: ID unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’un agent termine son exécution.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Émis au démarrage d’une session de navigateur.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Émis lorsqu’une session de navigateur se termine.
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 unique de cet événement.
format: uuid
type: string
message:
type: string
occurredAt:
format: date-time
type: string
phase:
enum:
- planning
- working
- finalizing
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsque l’orchestrateur signale une progression.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
text:
type: string
type:
description: Résumé du raisonnement de l’agent.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
parameters:
description: L’entrée transmise à l’outil (JSON arbitraire).
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Émis au démarrage d’un appel d’outil.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
result:
description: Le résultat renvoyé par l’outil (JSON arbitraire).
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Émis lorsqu’un appel d’outil se termine.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’un artefact de sortie est modifié.
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 unique de cet événement.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: "Numéro de séquence monotone de l’agent émetteur\_; utilisez-le pour ordonner les événements."
type: integer
runId:
description: L’ID de la tâche d’agent à laquelle appartient cet événement.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Émis lorsqu’une erreur non fatale survient durant l’exécution.
enum:
- error.occurred
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- error
title: error.occurred
type: object
AgentTraceAgent:
description: Identité de l’agent ayant émis l’événement.
properties:
id:
format: uuid
type: string
name:
type: string
parentId:
description: ID de l’agent parent (présent pour les sous-agents).
format: uuid
type: string
role:
enum:
- orchestrator
- subagent
- system
type: string
required:
- id
- role
- name
type: object
AgentTraceError:
description: Erreur structurée associée aux événements terminaux et d’erreur.
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: Descripteur d’une modification apportée à un artefact de sortie.
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: >-
Chemin de l’artefact dans l’espace de travail, par ex.
/workspace/data.json.
type: string
snapshotId:
description: >-
Utilisez GET /agent/{jobId}/snapshots/{snapshotId} pour récupérer le
contenu de cet instantané.
format: uuid
type: string
sourceToolCallId:
description: L’appel d’outil ayant produit cette modification, le cas échéant.
type: string
required:
- kind
- artifactId
- snapshotId
- change
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````