Skip to main content
GET
Obter o rastreamento de execução de um job 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.

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 custoscreditsUsed 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 subagents — 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. 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 para ver as instruções de integração automatizada.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

jobId
string<uuid>
obrigatório

O ID do job do agente

Parâmetros de consulta

liveView
enum<string>

Se "true", inclua as sessões do navegador atualmente ativas com URLs de visualização em tempo real.

Opções disponíveis:
true,
false

Resposta

Resposta bem-sucedida

activeBrowserSessions
object[]

Sessões de navegador ativas no momento (presentes apenas quando liveView=true).

creditsUsed
number

Créditos consumidos até o momento, limitados a maxCredits, se definido.

events
(run.started · object | run.cancel_requested · object | run.finished · object | agent.started · object | agent.finished · object | browser.session.started · object | browser.session.finished · object | progress.reported · object | reasoning.summary · object | tool_call.started · object | tool_call.finished · object | artifact.updated · object | error.occurred · object)[]

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.

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.

id
string<uuid>
success
boolean