Why a correct address and credential can still fail
Pointing a coding agent at a new model server can fail even when the address and credential are right, because the agent and the server may follow different API contracts.
When we wire Claude Code, Codex, pi, or OpenCode to a model server, we check what each client documents about the contract it sends, where translation between contracts can drop features, and how to test the route before relying on it.
Our coding agent accepts a new server address, and the server advertises an OpenAI-compatible API. We then check whether the agent can send a request, receive a tool call, and continue after the tool returns, because an incompatible API surface breaks that loop even with the correct address and credential.
We take five steps in order.
- Name the contract on each side of the connection.
- Find the integration point where translation happens.
- Read what each client documents about its contract.
- Check how tool calls and streams cross the boundary.
- Test the route and record the result.
What "OpenAI-compatible" leaves unsaid
Step one is to name the contract on each side, because the compatibility label does not name one.
An API contract defines the structured requests, responses, stream events, and errors exchanged at an interface. A stream delivers a response as a series of events instead of returning the whole result at once, and the contract says what those events mean and how the client ties them to the response.
We keep four interfaces apart.
- Anthropic Messages accepts structured conversation messages and generates the next message.
- OpenAI Chat Completions generates a response from a conversation supplied as messages.
- OpenAI Responses has its own interface for creating and managing model responses.
- We group other provider-specific APIs in a fourth category, which may contain different protocols.
Those names identify contracts, while credentials and available models are separate details. The label "OpenAI-compatible" leaves open whether the server implements Chat Completions, Responses, and the features our client needs, so we check each one.

Figure text
Separate stations are labelled Anthropic Messages, OpenAI Chat Completions, OpenAI Responses, and other provider-specific APIs, with no comparison between them.
- Four formats, kept apart
- Anthropic Messages (square plate)
- OpenAI Chat Completions (diamond)
- OpenAI Responses (octagon plate)
- OpenAI-compatible names no single format. Find out which one the server implements before relying on it.
- 1 The label arrives
- 2 Could mean this
- 3 Or this
- Anthropic Messages
- OpenAI Chat Completions
- OpenAI Responses
- Other provider-specific APIs
- A server's label
- Which one? Not stated
- The label does not say which. We check each one, and the features our agent needs.
Sources: [1] Messages - Claude API Reference; [2] Responses | OpenAI API Reference; [3] Chat | OpenAI API Reference.
Where translation between contracts loses features
Step two is to find the integration point, because when the client and the server follow different contracts something has to translate between them, and that is where features go missing.
A translation component copies the relevant information between two contracts and translates the reply. Even when both sides speak JSON, software translation can lose tool semantics, stream structure, cache controls, or error details.
A native adapter is a client-side integration with a provider's interface, which transforms the application's internal objects without a separate gateway service. A translation gateway accepts a client-facing contract and maps it to an upstream contract across a service boundary.
Feature loss can occur at either of the two integration points.
How the native adapter path reaches the provider
The native path connects the agent to the provider without a separate service.
In a native path, the client's harness (its orchestration code) prepares the conversation and the available tools, then hands that request to its provider adapter. The adapter uses the provider's authentication and API behavior to contact the endpoint, and the provider's response comes back through the adapter before the harness consumes it.
The pi provider architecture uses native adapters. Each provider owns its model catalog, authentication, and stream behavior, and the model collection routes requests to the provider that owns the selected model.
The pi-ai README names pi's shared internal implementations, including these three.
anthropic-messagesopenai-responsesopenai-completions
Individual providers may support only some of the contracts.
The pi coding-agent model guide separately describes three connection options.
- built-in providers
- compatible endpoints configured through
models.json - extensions for custom protocols or authentication

Figure text
A coding agent sends a request through its native adapter to a provider endpoint outside the agent's boundary. The response crosses back through the adapter to the client.
- The adapter inside the agent
- Inside the agent (upright, round)
- Provider's format (sideways, cut)
- No separate service on this path. The adapter is still a conversion point, so features can be lost here too.
- 1 Request, inside the agent
- 2 Request, provider's format
- 3 Reply, provider's format
- 4 Reply the agent can use
- Coding agent: Its harness prepares the conversation and the tools
- Native adapter: Part of the agent; converts both directions
- Provider API: Configured endpoint
- Coding-agent boundary
- Provider boundary
- The adapter turns the reply into something the agent can use.
Sources: [1] pi ai; [2] pi models; [3] Providers | OpenCode.
How a translation gateway converts both directions
The second path puts a translation gateway between the agent and the upstream API.
Suppose a client sends requests in the Messages format while the chosen upstream expects another contract. The gateway converts requests into the upstream contract and converts upstream responses so the client can read them. LiteLLM's Claude Code tutorial describes the sequence.
- receive Messages requests
- translate them to the target provider's format
- forward them
- translate the response back
Which upstream API it uses and which features map across depend on the configuration and the LiteLLM version.
Claude Code's gateway guidance says third-party gateways operate without Anthropic's endorsement, maintenance, or auditing, and Anthropic's support also excludes routing Claude Code to non-Claude models through any gateway.

Figure text
A coding agent sends a client-format request through a translation gateway to an upstream API, whose response returns through that gateway. The gateway has its own ownership boundary.
- The converter as its own service
- Messages format (upright card)
- Unnamed upstream format (sideways)
- The gateway is a second place where features can be lost. With LiteLLM, which upstream API it uses and which features map across depend on the configuration and the version.
- 1 Request, Messages format
- 2 Request, upstream format
- 3 Reply, upstream format
- 4 Reply, Messages format
- Coding agent: Sends requests in the Messages format
- Translation gateway: A separate service; converts both directions
- Configured upstream API: Expects another format
- Reply
- Gateway owner
- Upstream owner
- The gateway converts the reply back so the agent can read it.
Sources: [1] Use Claude Code with Non-Anthropic Models | liteLLM; [2] Other LLM gateways - Claude Code Docs.
What the four clients document
Step three is to read what each client says about its own contract.
Codex. The configuration reference lists responses as the only supported value of model_providers.<id>.wire_api, and as the default when omitted.
It has separate base-URL and credential fields, but it leaves some built-in provider adapters and Codex product surfaces unlisted.
Claude Code. Claude Code documents a Messages-facing gateway route.
Provider-specific cloud integrations can change the client-facing format and configuration.
LiteLLM documents opt-in model discovery via CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1, which needs Claude Code v2.1.129 or later, and its tutorial says they checked discovery against v2.1.247.
pi. The pi provider documentation puts authentication and streaming with each provider and names the internal API implementations. The pi model guide covers application-level configuration.
OpenCode. The provider guide describes its use of AI SDK and Models.dev, provider configuration, and API-key setup through /connect.
The AI SDK OpenAI provider supports Responses, Chat, and completion APIs at the library level.
To learn which of the library's supported APIs an OpenCode release uses for a model, we look at the installed application and dependency versions, the configuration, and the actual calls.
Where tool calls and streams show partial compatibility
Step four is to check tool calls and streams, because a server can accept the request and still encode these two parts differently from the client.
Messages carries its system prompt separately from the conversation messages, and tool definitions use tools entries with name and input_schema.
Chat Completions represents system or developer instructions as role-tagged messages and function definitions under tools[].function with name and parameters.
The call/result link differs too.
Messages returns a tool_use content block with an id, then accepts a tool_result block whose tool_use_id refers to that call (Messages schema).
In Chat Completions, the model returns a tool call, and the caller submits its result as a separate message with role: "tool" and the matching tool_call_id (Chat Completions schema).
We map each field explicitly across the boundary and check usage reporting and errors separately from the final text, because a response can display correctly with a missing stream event or cost field.
Streams carry their own ordering rules.
In pi's streaming contract, text, thinking, and tool-call events may interleave.
The same event reference defines error, with reason set to "error" or "aborted" and an error field carrying an AssistantMessage with partial content.
Consumers must use contentIndex to tie a delta or end event to its content block.
For example, a stream could take this order.
- open text
- open a tool call
- deliver more text before the tool arguments finish
A consumer that hands every later delta to the most recently opened block would attach that text to the tool call. Other providers may stream differently.
The same tool call in all three APIs
One harmless weather tool call, sent to each API, shows how the three request and response shapes differ.
Anthropic Messages
Request with curl:
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"model": "claude-haiku-5-5",
"max_tokens": 256,
"tools": [{
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}],
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"}
]
}'
The same request with the Python SDK:
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY
response = client.messages.create(
model="claude-haiku-5-5",
max_tokens=256,
tools=[{
"name": "get_weather",
"description": "Get the current weather for a city.",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
},
"required": ["city"],
},
}],
messages=[
{"role": "user", "content": "What is the weather in Paris right now?"},
],
)
print(response.model_dump_json(indent=2))
Response, trimmed:
{
"id": "msg_...",
"type": "message",
"role": "assistant",
"model": "claude-haiku-5-5",
"content": [
{
"type": "tool_use",
"id": "toolu_...",
"name": "get_weather",
"input": {"city": "Paris"}
}
],
"stop_reason": "tool_use",
"usage": {"input_tokens": 385, "output_tokens": 50}
}
OpenAI Chat Completions
Request with curl:
curl https://api.openai.com/v1/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "gpt-6-luna",
"tools": [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
}],
"messages": [
{"role": "user", "content": "What is the weather in Paris right now?"}
],
"reasoning_effort": "none"
}'
The same request with the Python SDK:
import openai
client = openai.OpenAI() # reads OPENAI_API_KEY
completion = client.chat.completions.create(
model="gpt-6-luna",
tools=[{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
},
"required": ["city"],
},
},
}],
messages=[
{"role": "user", "content": "What is the weather in Paris right now?"},
],
reasoning_effort="none",
)
print(completion.model_dump_json(indent=2))
Response, trimmed:
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "gpt-6-luna-2026-09-22",
"choices": [
{
"index": 0,
"finish_reason": "tool_calls",
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_...",
"type": "function",
"function": {
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}"
}
}
]
}
}
],
"usage": {
"prompt_tokens": 139,
"completion_tokens": 17,
"total_tokens": 156
}
}
OpenAI Responses
Request with curl:
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "content-type: application/json" \
-d '{
"model": "gpt-6-luna",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}],
"input": "What is the weather in Paris right now?"
}'
The same request with the Python SDK:
import openai
client = openai.OpenAI() # reads OPENAI_API_KEY
response = client.responses.create(
model="gpt-6-luna",
tools=[{
"type": "function",
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"},
},
"required": ["city"],
},
}],
input="What is the weather in Paris right now?",
)
print(response.model_dump_json(indent=2))
Response, trimmed:
{
"id": "resp_...",
"object": "response",
"status": "completed",
"model": "gpt-6-luna",
"output": [
{
"type": "function_call",
"id": "fc_...",
"call_id": "call_...",
"name": "get_weather",
"arguments": "{\"city\":\"Paris\"}",
"status": "completed"
}
],
"usage": {
"input_tokens": 57,
"output_tokens": 18,
"total_tokens": 75
}
}
The responses are captures of our own calls, and the request and response bodies are the APIs' own shapes.
The endpoint and auth header lines are the public ones; each platform we used has its own URL and credential header.
The Messages response came from claude-haiku-5-5 with the anthropic Python SDK 2.3.0, which sends anthropic-version 2026-10-21, through Claude Platform on AWS, which serves the same Claude API at its own base URL with IAM request signing; the response shown is the raw HTTP body.
The Chat Completions and Responses replies came from gpt-6-luna through an Azure OpenAI deployment, sent with curl and with the openai Python SDK 3.39.0; the bodies shown are the curl responses.
That deployment serves the same Chat Completions and Responses API shape.
We shortened the ids, removed provider-specific fields such as content filter results, routing and latency data, and kept the fields that show the tool call, the stop reason and the token counts.
On our Azure deployment of gpt-6-luna, Chat Completions refused function tools with an invalid_request_error until we set reasoning_effort to "none", which is why that field is in the request.
The error read: "Function tools with reasoning_effort are not supported for gpt-6-luna in /v1/chat/completions. To use function tools, use /v1/responses or set reasoning_effort to 'none'."
Sources: [1] Tool use with Claude - Claude Platform Docs; [2] Chat | OpenAI API Reference; [3] Function calling | OpenAI API.
The tool definition, the returned call and the field that ends the turn have different names in each API, so a translator has to map every one of them. In each response above the call is still only a request, nothing has run, and what the client does next is the subject of Tool-call trust in coding agents.

- Anthropic Messages: one harmless weather tool call, sent to this API, returns a
tool_usecontent block with anid. - OpenAI Chat Completions: the same call, sent to this API, returns a tool call, and the caller submits its result with the matching
tool_call_id. - OpenAI Responses: the same call, sent to the third API; the tool definition, the returned call and the field that ends the turn have different names in each API.
A compatibility worksheet
The worksheet puts the documented surface for each client side by side.
Note each client's exact version next to the API surface, configuration and authentication it documents, and what you see when you try it.
Sources: Configuration Reference | ChatGPT Learn, pi ai, pi models, Providers | OpenCode, OpenAI | AI SDK, Use Claude Code with Non-Anthropic Models | liteLLM, Other LLM gateways - Claude Code Docs.
| Client | API surface and configuration | Authentication |
|---|---|---|
| Codex | Custom-provider wire_api accepts responses | Separate env_key field |
| Claude Code | /v1/messages via ANTHROPIC_BASE_URL in LiteLLM's example; model discovery is opt-in (see "What the four clients document") | LiteLLM's example sets ANTHROPIC_AUTH_TOKEN |
| pi | Compatible endpoints use models.json with providers.<id>.baseUrl and api; streams associate events by contentIndex and may interleave, and pi defines an error event | Each provider defines its own authentication |
| OpenCode | OpenCode depends on the AI SDK and uses provider configuration with the baseURL option | API keys are set up through /connect |
How we test a route before we trust it
Step five is to test the route ourselves, so the worksheet shows what the route did next to what the docs say.
We add columns to the worksheet for the tool round trip, streaming, and error behavior, then fill them in with this procedure.
- Before sending anything, write down four facts about the route.
- the client and adapter versions
- the exact endpoint
- the model ID
- the credential type
- Send a harmless streamed text request.
- Send a harmless tool call and follow it through result submission to the final answer.
- Keep the sanitized stream events, usage, and error outcomes for that route, with a column for each check.

Figure text
Four steps: record the client and adapter versions, endpoint, model ID and credential type; send a harmless streamed text request; send a harmless tool call and follow it through result submission to the final answer; keep sanitized stream events, usage and error outcomes in one column per check.
- Test one route, four steps
- Lit row: written down, not judged
- The worksheet now shows what the route did next to what the docs say. This figure shows the procedure; your own run supplies the results.
- 1 Test request out
- 2 What came back
- Coding agent: The client under test
- Model server: The exact route we plan to use
- Worksheet: the route: Step 1. Record the route
- Worksheet: the outcomes
- Final answer
- Client and adapter versions; Exact endpoint; Model ID; Credential type
- Streaming; Tool round trip; Errors
- Step 4. Keep what came back, one column per check.
Before we rely on a route
We name the contract the client sends and the contract the server implements, then run the test procedure above on the exact route we plan to use.
Source versions
The Messages reference labels 2026-10-21 as its schema API version, distinct from the client's release version. The pi-ai README is pinned to commit 55a5c6914570e2ae31ca36297654483bbbf46883, and the pi model guide link follows main.
What an attacker targets here
Every API above returns a tool call as data, so the attack surface is what the client does with that call and with the result it sends back.
- Model output passed to a shell, exec or eval turns a prompt into remote code execution, the case OWASP describes as improper output handling. We run a program only with a fixed argument list, never a command string the model wrote, as Tool-call trust in coding agents explains.
- Content a tool fetches, such as a web page, comes back as a tool result and can carry an attacker's instructions into the next request. We mark that content as untrusted and check each call it prompts on its own terms, as the section on tool results shows.