# Agent Hints (/concepts/agent-hints)



**Agent Hints** are how a client tells the platform what it wants without naming how to do it. A hint says "prefer reuse at project scope" or "this is interactive, aim for 500ms TTFT". It never says "set this provider's cache-control breakpoint here" or "use that engine's flag". The platform's adapters translate neutral intent into provider-specific capabilities. That translation layer is the whole value: your code stays portable across providers and runtimes.

## Native `/v2` form [#native-v2-form]

On `/v2`, hints are a structured object. Every section is optional.

```json
{
  "agent_hints": {
    "version": "2026-06-01",
    "session": {
      "session_id": "ses_01jy...",
      "branch_id": "br_01jy...",
      "expected_branch_version": 17
    },
    "state": {
      "bundle_refs": ["bnd_01jy..."],
      "placement_preference": "stable_prefix"
    },
    "reuse": {
      "preference": "prefer",
      "scope": "project",
      "retention_preference": "extended_when_available"
    },
    "qos": {
      "class": "interactive",
      "target_ttft_ms": 500,
      "deadline_ms": 5000,
      "degrade_policy": "allow_compatible_fallback"
    },
    "routing": {
      "region_policy": "us_only",
      "execution_profiles": ["managed_provider", "byok", "byoc"],
      "data_boundary": "project"
    },
    "safety": {
      "retry_safety": "idempotent_generation_only",
      "tool_side_effect_mode": "external_commit_required"
    }
  }
}
```

The `qos` block maps directly onto a [QoS request](/concepts/qos); missing fields fall back to neutral defaults (standard class, compatible fallback).

## `/v1` transport [#v1-transport]

On `/v1` the body must stay byte-for-byte OpenAI-shaped, so hints travel by reference in a header:

```http
Agent-Hints-Ref: ah_01jy...
```

For simple deployments, a small inline form is allowed:

```http
Agent-Hints: <base64url-encoded-json>
```

<Note>
  A client that sends no hint header still gets correct OpenAI behavior on `/v1`. Hints are purely additive - this is the [API surface](/concepts/api-surfaces) extension rule in action.
</Note>

## Design rules [#design-rules]

The contract is governed by a short, strict set of rules.

<AccordionGroup>
  <Accordion title="Unknown hints are ignored safely or rejected explicitly">
    A newer client can send richer hints to an older backend without breaking. Unrecognized sections are dropped, never misinterpreted.
  </Accordion>

  <Accordion title="Hints are not guarantees">
    A hint expresses a preference. The platform honors what the resolved provider can actually deliver and reports the rest as accepted intent.
  </Accordion>

  <Accordion title="The platform reports which hints were honored">
    Every response can tell you which sections were enforced end-to-end versus recorded as intent. Today QoS is enforceable through the [outcome object](/concepts/qos); reuse, routing, state, and session are recorded as accepted intent.
  </Accordion>

  <Accordion title="Hints cannot weaken isolation or override retention">
    No hint can cross a tenant boundary or relax a customer's retention rules. Security and retention policy always win over a preference.
  </Accordion>

  <Accordion title="Adapters map neutral hints to provider capabilities">
    A `reuse.preference: prefer` hint becomes an Anthropic cache-control breakpoint, a Gemini cache directive, or an OpenAI prefix-ordering choice - whatever the resolved target supports.
  </Accordion>
</AccordionGroup>

## Versioning [#versioning]

The contract is dated (`version: "2026-06-01"`). Pin the version you built against so a future contract revision cannot change the meaning of a field underneath you, and so the platform can apply the right parsing rules to your hints.

<CardGroup cols="2">
  <Card title="QoS" icon="stopwatch" href="/concepts/qos">
    The class and target fields the QoS hint block carries.
  </Card>

  <Card title="Agent Hints API" icon="code" href="/api-v2/agent-hints">
    Store and reference hint objects.
  </Card>
</CardGroup>