> ## 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.
# Obter rastro do agente
Cada execução de agente registra um **rastro de execução** canônico: um fluxo ordenado de eventos que descreve tudo o que a execução fez — quais ferramentas chamou e o que elas retornaram, resumos de raciocínio, atualizações de progresso, sessões do navegador e mudanças nos artefatos de resultado. Esse é o mesmo fluxo de eventos que alimenta a visualização de Atividade em tempo real no [Agent Playground](https://www.firecrawl.dev/app/agent).
## Para que serve
* **Depuração de execuções** — veja as buscas, os scrapes e as extrações exatos realizados pelo agente, a entrada (`tool_call.started`) e o resultado (`tool_call.finished`) de cada ferramenta, além de identificar onde uma execução falhou (`error.occurred`, bem como o `outcome` e o `error` estruturado do evento terminal `run.finished`).
* **UIs de progresso em tempo real** — consulte o rastro enquanto um job estiver em `processing` para mostrar o que o agente está fazendo em tempo real. Os eventos `progress.reported` informam a fase da execução (`planning`, `working`, `finalizing`) com uma mensagem compreensível para humanos, e os eventos `reasoning.summary` descrevem o raciocínio do agente.
* **Visualização do navegador em tempo real** — passe `?liveView=true` enquanto uma execução estiver em andamento para obter `activeBrowserSessions`: as sessões ativas do navegador da execução, cada uma com uma `liveViewUrl` que pode ser incorporada para acompanhar (ou demonstrar) o agente navegando.
* **Acompanhamento de custos** — `creditsUsed` informa os créditos consumidos até o momento, limitados ao `maxCredits` da execução, se definido.
## Como funciona
Os eventos são emitidos pelos agentes da execução — o `orchestrator` e seus `subagent`s — e cada evento identifica seu emissor no campo `agent`. As tarefas no navegador ocorrem dentro da própria sessão de navegador de um agente e são reportadas por eventos `browser.session.*`, não por agentes de navegador separados. Ordene os eventos por `producerSequence` (por agente emissor). O campo `type` distingue as 13 variantes de evento; consulte o esquema de resposta abaixo para ver a lista completa e os campos de cada variante.
Os eventos `artifact.updated` não incluem o conteúdo do artefato — eles fazem referência a ele por `snapshotId`, que você busca com o [endpoint de snapshot](/pt-BR/api-reference/endpoint/agent-snapshot).
Os eventos podem continuar chegando por um momento após a chegada de `run.finished`; portanto, se você estiver consultando uma execução em andamento, mantenha uma breve janela de espera antes de renderizar o estado final.
Os rastros são registrados em execuções do Spark 2 — ou seja, em todas as novas execuções. Jobs iniciados em modelos Spark 1 antes de serem descontinuados não têm rastros e retornam `400`.
> Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver as instruções de integração automatizada.
## OpenAPI
````yaml pt-BR/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 interagir com os serviços do Firecrawl e executar tarefas de web
scraping e crawling.
title: Firecrawl API
version: v2
servers:
- url: https://api.firecrawl.dev/v2
security:
- bearerAuth: []
paths:
/agent/{jobId}/trace:
parameters:
- description: O ID do job do agente
in: path
name: jobId
required: true
schema:
format: uuid
type: string
get:
tags:
- Agent
summary: Obter o rastreamento de execução de um job do agente
operationId: getAgentTrace
parameters:
- description: >-
Se "true", inclua as sessões do navegador atualmente ativas com URLs
de visualização em tempo real.
in: query
name: liveView
required: false
schema:
enum:
- 'true'
- 'false'
type: string
responses:
'200':
content:
application/json:
schema:
properties:
activeBrowserSessions:
description: >-
Sessões de navegador ativas no momento (presentes apenas
quando 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 até o momento, limitados a maxCredits,
se definido.
type: number
events:
description: >-
Eventos canônicos de execução da execução; ordenados por
producerSequence. Os eventos artifact.updated contêm os
valores de snapshotId usados pelo endpoint de snapshots.
items:
$ref: '#/components/schemas/AgentTraceEvent'
type: array
id:
format: uuid
type: string
success:
type: boolean
type: object
description: Resposta bem-sucedida
'400':
content:
application/json:
schema:
properties:
error:
example: Trace is only available for Spark 2 extracts
type: string
type: object
description: >-
Solicitação inválida — o ID do job não é um UUID válido ou o job não
foi executado no spark-2 (os rastreamentos estão disponíveis apenas
para jobs de agente do spark-2).
'404':
content:
application/json:
schema:
properties:
error:
example: Agent job not found
type: string
type: object
description: Job do agente não encontrado
security:
- bearerAuth: []
components:
schemas:
AgentTraceEvent:
description: >-
Um evento de execução canônico de uma execução de agente. Todos os
eventos contêm os campos de envelope schemaVersion, eventId, runId,
occurredAt, producerSequence e agent; o campo type diferencia a
variante. Os eventos usage.recorded são internos e nunca são expostos, e
os eventos agent.started omitem o campo model.
discriminator:
propertyName: type
oneOf:
- properties:
agent:
$ref: '#/components/schemas/AgentTraceAgent'
eventId:
description: ID exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Emitido quando a execução é iniciada.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
reason:
enum:
- user
type: string
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: >-
Emitido quando o cancelamento é solicitado (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: >-
Nulo quando o resultado é succeeded; caso contrário, o erro
estruturado.
nullable: true
eventId:
description: ID exclusivo deste 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 sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Evento terminal da execução.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Emitido quando um agente (orquestrador ou subagente) é iniciado.
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 quando o resultado é succeeded; caso contrário, o erro
estruturado.
nullable: true
eventId:
description: ID exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
outcome:
enum:
- succeeded
- failed
- cancelled
- refused
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Emitido quando um agente é finalizado.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Emitido quando uma sessão de navegador é iniciada.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
sessionId:
type: string
type:
description: Emitido quando uma sessão de navegador é finalizada.
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 exclusivo deste 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 sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Emitido quando o orquestrador informa o progresso.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
text:
type: string
type:
description: Um resumo do raciocínio do 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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
parameters:
description: A entrada passada para a ferramenta (JSON arbitrário).
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Emitido quando uma chamada de ferramenta é iniciada.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
result:
description: O resultado retornado pela ferramenta (JSON arbitrário).
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
toolCallId:
type: string
toolName:
type: string
type:
description: Emitido quando uma chamada de ferramenta é finalizada.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Emitido quando um artefato de resultado é alterado.
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 exclusivo deste evento.
format: uuid
type: string
occurredAt:
format: date-time
type: string
producerSequence:
description: >-
Número de sequência monotônico do agente emissor; ordene os
eventos por ele.
type: integer
runId:
description: O ID do job do agente ao qual este evento pertence.
format: uuid
type: string
schemaVersion:
enum:
- 1
type: integer
type:
description: Emitido quando ocorre um erro não fatal durante a execução.
enum:
- error.occurred
type: string
required:
- schemaVersion
- eventId
- runId
- occurredAt
- producerSequence
- agent
- type
- error
title: error.occurred
type: object
AgentTraceAgent:
description: Identidade do agente que emitiu o evento.
properties:
id:
format: uuid
type: string
name:
type: string
parentId:
description: ID do agente pai (presente em subagentes).
format: uuid
type: string
role:
enum:
- orchestrator
- subagent
- system
type: string
required:
- id
- role
- name
type: object
AgentTraceError:
description: Erro estruturado anexado a eventos terminais e de erro.
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: Descritor de uma mudança em um artefato de resultado.
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: >-
Caminho do artefato no espaço de trabalho, por exemplo,
/workspace/data.json.
type: string
snapshotId:
description: >-
Use GET /agent/{jobId}/snapshots/{snapshotId} para buscar o conteúdo
deste snapshot.
format: uuid
type: string
sourceToolCallId:
description: A chamada de ferramenta que produziu esta mudança, quando aplicável.
type: string
required:
- kind
- artifactId
- snapshotId
- change
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````