> ## 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.
# Obtener la traza del agente
Cada ejecución de un agente registra una **traza de ejecución** canónica: una secuencia ordenada de eventos que describe todo lo que hizo la ejecución —las herramientas que llamó y lo que devolvieron, resúmenes de razonamiento, actualizaciones de progreso, sesiones de navegador y cambios en sus artefactos de salida—. Es la misma secuencia de eventos que impulsa la vista de actividad en tiempo real en [Agent Playground](https://www.firecrawl.dev/app/agent).
## Para qué sirve
* **Depuración de ejecuciones** — consulta las búsquedas, los scrapeos y las extracciones exactos que realizó el agente, la entrada (`tool_call.started`) y el resultado (`tool_call.finished`) de cada herramienta, y dónde falló una ejecución (`error.occurred`, así como el `outcome` y el `error` estructurado del evento final `run.finished`).
* **Interfaces de usuario de progreso en tiempo real** — consulta periódicamente la traza mientras un trabajo está en `processing` para mostrar lo que hace el agente en tiempo real. Los eventos `progress.reported` incluyen la fase de la ejecución (`planning`, `working`, `finalizing`) con un mensaje legible para las personas, y los eventos `reasoning.summary` describen el razonamiento del agente.
* **Vista del navegador en tiempo real** — pasa `?liveView=true` mientras una ejecución está en curso para obtener `activeBrowserSessions`: las sesiones activas del navegador de la ejecución, cada una con una `liveViewUrl` que puedes integrar para observar (o mostrar en una demostración) cómo navega el agente.
* **Seguimiento de costos** — `creditsUsed` informa de los créditos consumidos hasta el momento, con un límite de `maxCredits` para la ejecución si se configuró.
## Cómo funciona
Los eventos los emiten los agentes de la ejecución —el `orchestrator` y sus `subagent`s—, y cada evento identifica a su emisor en el campo `agent`. El trabajo del navegador se realiza dentro de la propia sesión de navegador del agente y se notifica mediante eventos `browser.session.*`, no a través de agentes de navegador independientes. Ordena los eventos por `producerSequence` (para cada agente emisor). El campo `type` distingue las 13 variantes de eventos; consulta el esquema de respuesta a continuación para ver la lista completa y los campos de cada variante.
Los eventos `artifact.updated` no incluyen el contenido del artefacto; hacen referencia a él mediante `snapshotId`, que puedes recuperar con el [endpoint de instantáneas](/es/api-reference/endpoint/agent-snapshot).
Los eventos pueden seguir llegando durante un breve periodo tras recibir `run.finished`, así que, si consultas periódicamente una ejecución activa, mantén abierta una breve ventana de espera antes de mostrar el estado final.
Las trazas se registran en las ejecuciones de Spark 2, es decir, en todas las ejecuciones nuevas. Los trabajos iniciados en modelos Spark 1 antes de su retirada no tienen trazas y devuelven `400`.
> ¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para obtener instrucciones de incorporación automatizada.
## OpenAPI
````yaml es/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 para interactuar con los servicios de Firecrawl y realizar tareas de
scraping y rastreo web.
title: Firecrawl API
version: v2
servers:
- url: https://api.firecrawl.dev/v2
security:
- bearerAuth: []
paths:
/agent/{jobId}/trace:
parameters:
- description: El ID del trabajo del agente
in: path
name: jobId
required: true
schema:
format: uuid
type: string
get:
tags:
- Agent
summary: Obtiene el rastreo de ejecución de un trabajo del agente
operationId: getAgentTrace
parameters:
- description: >-
Si es "true", incluye las sesiones de navegador activas actualmente
con URL de vista en vivo.
in: query
name: liveView
required: false
schema:
enum:
- 'true'
- 'false'
type: string
responses:
'200':
content:
application/json:
schema:
properties:
activeBrowserSessions:
description: >-
Sesiones de navegador actualmente activas (solo se incluye
cuando 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éditos consumidos hasta el momento, con un máximo de
maxCredits si se especificó.
type: number
events:
description: >-
Eventos canónicos de ejecución, ordenados por
producerSequence. Los eventos artifact.updated contienen
los valores snapshotId utilizados por el endpoint de
instantáneas.
items:
$ref: '#/components/schemas/AgentTraceEvent'
type: array
id:
format: uuid
type: string
success:
type: boolean
type: object
description: Respuesta correcta
'400':
content:
application/json:
schema:
properties:
error:
example: Trace is only available for Spark 2 extracts
type: string
type: object
description: >-
Solicitud incorrecta — el ID de trabajo no es un UUID válido o el
trabajo no se ejecutó en spark-2 (los rastreos solo están
disponibles para trabajos de agente de spark-2).
'404':
content:
application/json:
schema:
properties:
error:
example: Agent job not found
type: string
type: object
description: No se encontró el trabajo del agente
security:
- bearerAuth: []
components:
schemas:
AgentTraceEvent:
description: >-
Un evento de ejecución canónico de una ejecución del agente. Cada evento
incluye los campos de envoltura schemaVersion, eventId, runId,
occurredAt, producerSequence y agent; el campo type distingue la
variante. Los eventos usage.recorded son internos y nunca se exponen, y
los eventos agent.started omiten el campo model.
discriminator:
propertyName: type
oneOf:
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Se emite cuando comienza la ejecución.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
reason:
enum:
- user
type: string
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: >-
Se emite cuando se solicita la cancelación (mediante 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: >-
Nulo si el resultado es succeeded; de lo contrario, el error
estructurado.
nullable: true
eventId:
description: ID único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
- credit_limit_reached
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Evento terminal de la ejecución.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Se emite cuando se inicia un agente (orquestador o subagente).
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: >-
Nulo si el resultado es succeeded; de lo contrario, el error
estructurado.
nullable: true
eventId:
description: ID único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Se emite cuando finaliza un agente.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Se emite cuando se inicia una sesión de navegador.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Se emite cuando finaliza una sesión de navegador.
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 único de este evento.
format: uuid
type: string
message:
type: string
occurredAt:
format: date-time
type: string
phase:
enum:
- planning
- working
- finalizing
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Se emite cuando el orquestador informa del progreso.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
text:
type: string
type:
description: Un resumen del razonamiento del agente.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
parameters:
description: La entrada proporcionada a la herramienta (JSON arbitrario).
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Se emite cuando se inicia una llamada a una herramienta.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
result:
description: El resultado devuelto por la herramienta (JSON arbitrario).
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Se emite cuando finaliza una llamada a una herramienta.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Se emite cuando cambia un artefacto de salida.
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 único de este evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de secuencia monotónico del agente emisor; ordene los
eventos según este número.
type: integer
runId:
description: El ID del trabajo del agente al que pertenece este evento.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: >-
Se emite cuando se produce un error no fatal durante la
ejecución.
enum:
- error.occurred
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- error
title: error.occurred
type: object
AgentTraceAgent:
description: Identidad del agente que emitió el evento.
properties:
id:
format: uuid
type: string
name:
type: string
parentId:
description: ID del agente principal (presente en los subagentes).
format: uuid
type: string
role:
enum:
- orchestrator
- subagent
- system
type: string
required:
- id
- role
- name
type: object
AgentTraceError:
description: Error estructurado adjunto a eventos terminales y de error.
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: Descriptor de un cambio en un artefacto de salida.
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: >-
Ruta del espacio de trabajo del artefacto; p. ej.,
/workspace/data.json.
type: string
snapshotId:
description: >-
Páselo a GET /agent/{jobId}/snapshots/{snapshotId} para obtener el
contenido de esta instantánea.
format: uuid
type: string
sourceToolCallId:
description: >-
La llamada a una herramienta que produjo este cambio, cuando
corresponda.
type: string
required:
- kind
- artifactId
- snapshotId
- change
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````