Observability Signals for Agent Decisions

Direct answer

If you cannot answer which tool ran, with what args (redacted), at what cost, and why the run stopped, you cannot operate the agent. HazelJS gives you @hazeljs/observability traces and Inspector timelines.

Package: observability. Glossary: /glossary/trace.

Minimum signals (pin this)

Step 1Wire timelines in the same app

1. Configure observability peers beside AgentRuntime in your DI/starter app.
2. Persist timelines (FileTimelineStore locally is fine).
3. After execute, copy executionId and open the Inspector timeline / stream endpoint your starter exposes.
4. Confirm you see lookupOrder (and later processRefund waits).

Step 2Debug a real failure

Practice this once:

1. Break the adapter (throw or return { ok: false }).
2. Re-run the goal.
3. Find the run by executionId.
4. Write down: tool error class + stop reason + whether the model hallucinated a status anyway.

That exercise teaches more than reading dashboards alone.

Step 3Alerting that helps

Alert on:

• budget / maxSteps exhaustion spikes
• tool-error bursts
• approval queue age (HITL SLA)

Do not page on every model token.

Anti-patterns

• Pasting full tool payloads (with PII) into Slack
• Metrics without executionId
• “It failed” with no stop reason on the run record

Checkpoint

• You can pull a timeline for one Ops Desk executionId
• Stop reason is visible for success and for forced maxSteps
• Secrets are redacted in logs

What to do next

Operate from the terminal: /learn/agentic-development/hazel-cli-agent-ops