Skip to content

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.

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.

Terminal window
curl -s http://127.0.0.1:18000/.well-known/prism.json | python3 -m json.tool

An agent told “connect to Prism at this address” can read this document and set its own base URL and key variable.

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.

Terminal window
prism agent-context > PRISM.md
prism agent-context --format=json

The 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.

Headers on every routed answer: X-Prism-Provider (the provider that served it, after any failover), X-Prism-Model, X-Request-Id. See Headers.

[harness]
announce_served_model = true

Off 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_id equals the X-Request-Id header.
  • failover appears only when the request changed route, and holds at most the last 8 steps; attempts is the true total.
  • role_alias and trace_id are left out when they do not apply.
  • OpenAI clients that follow the specification ignore unknown top-level fields.

Send a stable X-Prism-Session header with each chat request, then:

Terminal window
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.

[harness]
annotate_chat_assistant_body = true

Off 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.