Choosing a Protocol
Choosing a Protocol
Section titled “Choosing a Protocol”ProxAI has two protocol decisions:
- Inbound protocol — what the local client sends, detected from the request path.
- Provider protocol — what ProxAI sends upstream, configured on the selected provider.
They can be the same for pass-through, or different when ProxAI performs a supported conversion.
Decision path
Section titled “Decision path”Client request path
/v1/responses, /v1/chat/completions, or /v1/messages
Route selection
default provider or explicit route by request_protocol + model
Provider protocol
provider.protocol controls outbound wire behavior
Upstream request
serialized in the selected provider protocol
Start with the client
Section titled “Start with the client”| Client speaks | Use inbound protocol | Typical reason |
|---|---|---|
| OpenAI Responses | openai_responses | Itemized output, modern Responses semantics, hosted-tool style payloads. |
| OpenAI Chat Completions | openai_chat_completions | Older SDKs, clients that expect choices[], or Chat Completions-only integrations. |
| Anthropic Messages | anthropic_messages | Clients that already emit Anthropic-style message payloads. |
Then choose the provider protocol
Section titled “Then choose the provider protocol”| Provider expects | Set provider.protocol | Notes |
|---|---|---|
| OpenAI Responses | openai_responses | Best fit for OpenAI-compatible Responses upstreams. |
| OpenAI Chat Completions | openai_chat_completions | Best fit for Chat Completions-only upstreams. |
| Anthropic Messages | anthropic_messages | Best fit for Anthropic-compatible /v1/messages upstreams. |
Provider names are labels. They do not imply protocol semantics. The provider protocol field is the semantic value.
Supported pairs
Section titled “Supported pairs”| Inbound \ Provider | Responses | Chat | Anthropic |
|---|---|---|---|
openai_responses | Pass-through | Supported | Supported |
openai_chat_completions | Unsupported | Pass-through | Supported |
anthropic_messages | Supported | Unsupported | Pass-through |
Unsupported pairs fail explicitly. ProxAI should not silently fall through to another provider if a route matched but the protocol pair is not implemented.
Common choices
Section titled “Common choices”Same protocol pass-throughUse when the client and provider already speak the same protocol.Responses client to Anthropic providerUseful when a local OpenAI-compatible client targets an Anthropic Messages upstream.Chat client to Anthropic providerUse explicit routes when only one model should cross protocols.Anthropic client to Responses providerUse only when the implemented pair preserves the behavior your client expects.
Lossiness questions
Section titled “Lossiness questions”Before choosing a cross-protocol pair, ask:
| Question | Why it matters |
|---|---|
| Does the client rely on exact output item ids? | Responses has itemized output and stable item identities that other protocols may not model the same way. |
| Does the provider emit tool calls incrementally? | Streaming tool-call chunks have protocol-specific identifiers and terminal events. |
| Does the client inspect stop or finish reasons? | Stop reasons are related but not identical across protocols. See status reference. |
| Does the client require provider-specific fields? | Provider-specific fields should not leak through a generic conversion boundary. |