Agent events

These fire only from the agent strategy. Use them to render a live activity feed of what the model is doing — which tools it called, what it reasoned, and whether it can actually see images.

Prop

Type

Vision detection fails open. If the model catalogue is unreachable or reports nothing for the model, onVisionStatus fires with enabled: true and the provider returns a clear error if the model truly cannot accept images — rather than the agent silently going text-only and producing incomplete extractions.

Example: human status events

onStatus carries a coarse, strategy-independent phase so you can render localized progress without matching internal step labels or tool names.

const result = await extract({
  artifacts,
  schema,
  strategy: agent({ provider: "openai", modelId: "gpt-4o-mini" }),
  events: {
    onStatus: ({ phase, message, percent }) => {
      // phase is one of: starting | analyzing | extracting | retrying | completed | failed
      console.log(phase, message?.key, percent);
    },
  },
});

When percent is null/absent, the strategy cannot report determinate progress (e.g. the agent strategy) — show an indeterminate spinner instead of a progress bar.

Example: progress bar

const result = await extract({
  artifacts,
  schema,
  strategy: parallel({ model, mergeModel: model, chunkSize: 8000 }),
  events: {
    onStep: ({ step, total, label }) => {
      process.stderr.write(`[${step}/${total ?? "?"}] ${label ?? "working"}\n`);
    },
    onTokenUsage: ({ totalTokens }) => {
      process.stderr.write(`Tokens so far: ${totalTokens}\n`);
    },
  },
});

Example: observe retries

const result = await extract({
  artifacts,
  schema,
  strategy: simple({ model }),
  events: {
    onRetry: ({ attempt, maxAttempts, reason }) => {
      console.log(`retry ${attempt}/${maxAttempts}: ${reason ?? "validation failed"}`);
    },
  },
});

Example: agent activity feed

const result = await extract({
  artifacts,
  schema,
  strategy: agent({ provider: "openai", modelId: "gpt-4o" }),
  events: {
    onVisionStatus: ({ enabled }) => {
      if (!enabled) console.warn("model has no vision — images will be skipped");
    },
    onAgentToolStart: ({ toolName, args }) => {
      console.log(`→ ${toolName}`, args);
    },
    onAgentToolEnd: ({ toolCallId, error }) => {
      if (error) console.log(`✗ ${toolCallId}: ${error}`);
    },
    onAgentReasoning: ({ thought }) => {
      console.log(`… ${thought}`);
    },
  },
});

Events & Observability

Available events

Agent events

Example: human status events

Example: progress bar

Example: observe retries

Example: agent activity feed

See also

On this page