Foresight on Traza Cloud

Foresight is the engine’s Fate Map and predictive fuses, running on your project’s cell. This page covers using them on Traza Cloud; how the numbers are computed, and their limits, are in How Foresight works and the engine’s Foresight guide.

What it needs from your spans

Foresight reads runs, so it needs what every run surface needs:

• A run id on every span: session.id (or the OpenInference and Traceloop equivalents), else each trace is its own run.
• An agent name: gen_ai.agent.name on the first step, else the service of the run’s earliest span. Runs are only compared with runs of the same agent in the same project.
• Outcomes, ideally declared: set session.outcome to success, failure or abandoned when a run ends. Without it, a run’s outcome is the status of the span that ended last, and a run that failed but ended on a successful span reads as a success.

A run with no declared outcome whose last span ended in the last 15 minutes is still active: it is unknown, left out of every rate, and counted.

Look at the map

In the console, open a project and choose Open explorer: the engine’s own Foresight view draws the Fate Map of each agent. Across projects, the organization’s Foresight page lists every agent with its success rate over time, its top fatal forks with example runs, and the behaviours that are new this week.

Over the API, with a read or full key:

# Every agent with completed runs in the last 30 days, and its base rate
curl -s https://api.trazadb.com/v1/fate/cohorts \
  -H "Authorization: Bearer $TRAZA_API_KEY"

# One agent's tree: every branch with its rate, 95% interval, cost and example runs
curl -s "https://api.trazadb.com/v1/fate/map?agent=support-agent" \
  -H "Authorization: Bearer $TRAZA_API_KEY"

# How runs like this one ended, and what the ones that succeeded did next
curl -s https://api.trazadb.com/v1/fate/runs/sess-9c21 \
  -H "Authorization: Bearer $TRAZA_API_KEY"

/v1/fate/map takes depth (default 12), min_support (default 3), max_nodes, task, and since/until in Unix nanoseconds (default: the last 30 days). Read the map’s calibration.depths[].skill before trusting a verdict: it is how much better than the agent’s average the map predicted runs it was not built from, and near zero means the agent’s fate does not depend on its path.

Stop runs heading for failure

Add min_success_odds to a fuse policy, with a full key:

curl -s https://api.trazadb.com/v1/fuses/policies \
  -H "Authorization: Bearer $TRAZA_API_KEY" \
  -d '{"name": "support", "match": {"service": "support-agent"},
       "limits": {"min_success_odds": 0.7, "max_cost_usd": 2.0}, "action": "stop"}'

At the pre-call check (POST /v1/fuses/check), when a run’s foresight stands on at least 30 earlier runs (foresight_min_support), the run has at least 3 steps (foresight_after_steps), and the upper bound of the 95% interval is below the odds, the policy’s action applies. Name the next tool in the check ("next": {"tool": "issue_refund"}) and the path is judged with that step appended. The upper bound is what is compared, so thin history stops nothing.

A foresight stop is a prediction made again at every check: it is not latched, it never rides on an ingest acknowledgement, and a reset does not clear it. To let a run go on against its history, reset it with a grant of lower odds:

curl -s -X POST https://api.trazadb.com/v1/fuses/runs/sess-9c21/reset \
  -H "Authorization: Bearer $TRAZA_API_KEY" \
  -d '{"grant": {"min_success_odds": 0.05}}'

Maps are built in the background and cached on the cell, so the first checks after a quiet spell, or after an erasure (which drops every cached map), see no foresight for a few seconds. Missing evidence is never treated as evidence of failure: the check answers without a foresight stop.

Be told

Mission Control shows each live run’s foresight verdict beside its guard verdict. An alert rule can fire when a run’s foresight reaches likely_failure, and deliver it as a push to your phone or an interactive Slack message with Approve, Kill and Nudge…; see Steer.

From your coding agent

With MCP connected (MCP), the foresee_run tool answers the same question for a run, in words and numbers the server computed.