Agent Hints
A vendor-neutral, versioned contract for expressing intent - reuse, QoS, routing, retry safety - without exposing any provider- or engine-specific knob.
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
On /v2, hints are a structured object. Every section is optional.
{
"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; missing fields fall back to neutral defaults (standard class, compatible fallback).
/v1 transport
On /v1 the body must stay byte-for-byte OpenAI-shaped, so hints travel by reference in a header:
Agent-Hints-Ref: ah_01jy...For simple deployments, a small inline form is allowed:
Agent-Hints: <base64url-encoded-json>A client that sends no hint header still gets correct OpenAI behavior on /v1. Hints are purely additive - this is the API surface extension rule in action.
Design rules
The contract is governed by a short, strict set of rules.
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.
Model aliases
Request a capability instead of a model string. Immutable alias releases, deterministic resolution, per-request resolution records, and no silent drift.
Quality of service
QoS classes, the request you submit, and the formal outcome object that makes the platform accountable for whether latency and reliability targets were actually met.