> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Envelope

> How an automated agent consumes the freshness, confidence, and quality-gate signal attached to every wrapped /v2 response.

The **agentic envelope** is the `meta._agentic` block attached to wrapped `/v2` responses. It exists so an automated consumer can make an act / wait / escalate decision from the response itself — without bespoke per-endpoint handling. It tells an agent:

1. How fresh the data is, and whether to retry shortly.
2. How confident the platform is in the answer.
3. Which upstream sources the answer was synthesized from.
4. Whether the response is fit for autonomous use, or whether a human or fallback path should review it first.

The envelope is **purely additive** — SDKs and dashboards that ignore `_agentic` keep working unchanged. For the full field reference see [Response envelope](/develop/concepts/response-envelope); for the freshness and quality-gate enums see [Freshness & staleness](/develop/concepts/freshness-and-staleness). This page is about *consuming* the signal.

## Wire shape (recap)

```json theme={null}
"meta": {
  "_agentic": {
    "schema_version": "1.0.0",
    "freshness": { "status": "realtime", "should_retry": false, "update_cadence_seconds": 300 },
    "confidence": 0.92,
    "sources": ["timescaledb", "archive_node"],
    "quality_gate": { "verdict": "pass", "reason": "", "degraded_fields": [] }
  }
}
```

Two headers mirror the body so middleware, HEAD requests, and cheap routing can act without parsing JSON:

* `X-Schema-Version` — mirrors `_agentic.schema_version` (currently `1.0.0`).
* `X-Quality-Gate` — mirrors `_agentic.quality_gate.verdict` (`pass` / `warn` / `fail`).

## How to consume it, by consumer type

| Consumer                 | Reads                                        | Recommended use                                                                                                                                   |
| ------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Dashboard / human**    | `meta` for cache-age, `data` for the payload | Ignore `_agentic`; render human-readable freshness from `computed_at`.                                                                            |
| **Backtest / batch ETL** | `freshness.computed_at`, `confidence`        | Pin `computed_at` as the cache key; drop rows where `confidence < 0.50` from training data.                                                       |
| **Realtime alerting**    | `X-Quality-Gate` header                      | Route `pass` to the rule engine; route `warn` to a human inbox; drop `fail`.                                                                      |
| **Autonomous agent**     | full `_agentic` block                        | Honor `should_retry` + `retry_after_seconds` for backoff; treat `verdict == fail` as a hard gate; log `degraded_fields` to the observation trail. |

## Agent rules of thumb

* **Back off correctly.** When `freshness.should_retry` is true, retry after `retry_after_seconds` if present, otherwise back off using `update_cadence_seconds` as the floor.
* **Treat `fail` as a hard gate.** A `quality_gate.verdict` of `fail` means *do not act unsupervised* — fall back to a cached or alternative source, or escalate to a human.
* **Inspect `degraded_fields`.** When non-empty, the listed JSON paths inside `data` were degraded, missing, or fell back to a less-authoritative source. For example, an oracle handler may emit `degraded_fields: ["per_aggregator_breakdown"]` when aggregator introspection timed out but the headline price held.
* **Refuse truncated payloads.** If `_agentic.truncated` is `true`, the response was clipped at an output cap — do not act on it; re-request with a narrower query.

## Trust framing

The same signal, framed for an institutional evaluator, lives at [Trust → Freshness & quality](/trust/data/freshness-and-quality): every response states how fresh and how trustworthy its numbers are, as a first-class field rather than a footnote.