Agent self-description
A model cannot read the headers of its own response, and many agent harnesses drop them. Prism publishes what an agent needs to know in documents it can fetch, and can copy the routing result into the response body.
/.well-known/prism.json
Section titled “/.well-known/prism.json”GET /.well-known/prism.json needs no key. It is served on the main address
(and on the control listener when [server] control_bind is set), not on the
managed address. It contains:
| Field | Content |
|---|---|
version |
Prism version |
endpoints |
Paths of the model, catalog, session and self-description endpoints |
model_selection |
Accepted model values: selector hints (auto, fast, smart, cheap, local), whether auto can route right now, the default strategy, the strategy header, role aliases (built-in names and those configured here), prism/* policy models with their availability |
attribution |
Which response headers name the serving model, whether the in-band copy is on, and the session query path |
connection |
Per-dialect paths and client variables, the key requirement and the published public URL; see Connect clients |
operator |
Operator actions an agent key with operator scopes can call on the managed address |
documentation |
Links to further documents |
It contains no provider keys, prices, spend, traces or operator state.
curl -s http://127.0.0.1:18000/.well-known/prism.json | python3 -m json.toolAn agent told “connect to Prism at this address” can read this document and set its own base URL and key variable.
/prism/agent-context
Section titled “/prism/agent-context”GET /prism/agent-context returns the same facts as Markdown, written to be
placed in an agent’s system prompt: how to choose a model, which policy models
are available right now and why others are not, how to read the response
headers. ?format=json returns the /.well-known/prism.json payload. It is
served where /.well-known/prism.json is and needs no key.
prism agent-context > PRISM.mdprism agent-context --format=jsonThe command reads from the running Prism, so the text matches the current
configuration. Set [server] docs_url to add a link to your own documentation.
Which model answered
Section titled “Which model answered”Headers on every routed answer: X-Prism-Provider (the provider that served
it, after any failover), X-Prism-Model, X-Request-Id. See
Headers.
In the response body
Section titled “In the response body”[harness]announce_served_model = trueOff by default. When on, successful non-streaming answers carry two extra
top-level JSON objects, and every answer carries the X-Prism-Served-By
header. The assistant’s message text is not changed.
{ "prism_served_by": {"provider": "openai", "model": "gpt-5-mini", "trace_id": "trace-..."}, "prism": { "served_model": "gpt-5-mini", "provider": "openai", "attempts": 2, "reason": "cheapest", "strategy": "cheap", "role_alias": "triage", "trace_id": "trace-...", "request_id": "prism-...", "failover": [ {"provider": "groq", "model": "llama-3.3-70b", "reason": "unavailable"}, {"provider": "openai", "model": "gpt-5-mini", "reason": "success"} ], "self_description": "/.well-known/prism.json" }}request_idequals theX-Request-Idheader.failoverappears only when the request changed route, and holds at most the last 8 steps;attemptsis the true total.role_aliasandtrace_idare left out when they do not apply.- OpenAI clients that follow the specification ignore unknown top-level fields.
By session
Section titled “By session”Send a stable X-Prism-Session header with each chat request, then:
curl -s http://127.0.0.1:18000/prism/session/last-served -H 'X-Prism-Session: my-session'{"served": true, "provider": "openai", "model": "gpt-5-mini", "trace_id": "trace-...", "request_id": "prism-...", "completed_at": "2026-10-07T07:36:18Z", "http_status": 200, "termination": "accepted"}It needs no key and returns the last completed request of that session, which a
later or parallel request can replace. Use X-Request-Id to identify one exact
response. Without the header the answer is 400 session_required. The path is
on the main address only; with an SDK whose base URL ends in /v1, call it at
the origin, not under /v1.
In the assistant text
Section titled “In the assistant text”[harness]annotate_chat_assistant_body = trueOff by default. Appends [Prism route: provider/model] to the assistant text of
/v1/chat/completions answers (non-streaming and streaming). This changes the
content the client sees; use it only for clients that show nothing but the
message text. A step that only calls tools gets no line, nor does an answer that
is only a bracketed marker for the client program, such as [SILENT], and Prism removes the
lines from the history the client sends back, so the model never sees them and
does not start writing them itself.