The world’s first unified interface for agent harnessesOpen Source4.3kPowered by UHP

InsightsNov 5, 202610 min read

LLM Proxy: What It Does, Where It Stops, and When You Need More

An LLM proxy puts many model providers behind one API. Learn what it does, how it differs from a gateway or router, and what agent products need beyond it.

One cobalt conduit passes through a frosted-glass wall and splits into three ceramic sockets, while a separate sealed capsule beyond them stays unconnected: a single pass-through reaches many providers but stops short of everything else an agent needs.
A proxy carries one request to many providers; what an agent needs beyond that call sits outside it.

TL;DR

An LLM proxy is a service that sits between your application and one or more model providers and exposes a single endpoint, so the application sends one request format and the proxy handles provider-specific authentication, transport, and response normalization. For a plain chat-completion workload that is often enough. For products built around AI agents, which hold sessions, read and write files, and run tools in a sandbox, a proxy covers only the model call, and the rest of the runtime remains your responsibility. This guide explains the proxy, its neighbors (the gateway and the router), the controls worth having, and where an agent harness layer begins.

  • An LLM proxy standardizes access to multiple providers behind one endpoint and one API key; a router chooses which model serves a request, and a gateway enforces identity, budgets, and policy.
  • The useful proxy features are retries, fallback across providers, load balancing, rate limiting, key isolation, and per-request logging of tokens and cost.
  • Keep the data plane stateless and cache control-plane facts such as pricing and routing rules on each node, so a control-plane outage does not stop traffic.
  • A proxy proxies model calls. Agent products also need session state, file handling, environment provisioning, and a way to swap the agent harness itself, which is the layer HarnessRouter provides.

What an LLM proxy is

Picture one request leaving your application. Without a proxy, your code must know the base URL, authentication scheme, request schema, streaming format, and error codes of each provider it calls. With a proxy, the application talks to one endpoint, typically in an OpenAI-compatible request shape, and the proxy translates the call for whichever upstream provider serves it.

The practical consequences are concentrated in four areas:

  • Single integration surface. Adding or replacing a provider becomes a configuration change in the proxy rather than a code change in every service.
  • Credential isolation. Provider API keys live in the proxy. Applications receive a scoped key that can be rotated or revoked without touching the upstream credentials.
  • Uniform observability. Every call passes through one point, so latency, token counts, errors, and cost can be recorded in one schema.
  • Central policy. Rate limits, allow-lists of models, and budget ceilings can be enforced once instead of per service.

These are the same reasons teams searching for a way to use multiple LLM providers through one API usually give: the first provider is easy, and the second and third multiply the integration surface.

Proxy, gateway, and router: three responsibilities

The three terms are used loosely, and vendors apply them to overlapping products. A workable distinction is by responsibility. One practitioner breakdown describes the proxy as the transport layer, the router as the decision layer that picks the model or provider, and the gateway as the policy layer that adds identity, rate limits, budget enforcement, and audit trails. In practice they are layers of one stack rather than separate products.

LayerCore questionTypical responsibilitiesState required
ProxyHow does the request reach the provider?Request translation, authentication, streaming, retriesMinimal
RouterWhich model should handle this request?Cost, latency, or quality-based selection, fallback orderRouting rules, health data
GatewayWho is calling, and what are they allowed to do?Per-team keys, budgets, quotas, audit logs, policyIdentities, ledgers

If you want the decision layer in depth, our guide to what an LLM router is and how model routing works covers selection policies. The rest of this article concentrates on the transport and policy responsibilities, and on what falls outside all three.

Features that matter when you evaluate a proxy

Routing, retries, and fallback

Provider APIs return rate-limit errors (HTTP 429), transient 5xx errors, and occasional timeouts. Handling these in application code duplicates logic across services. A proxy can absorb them by retrying with backoff, then falling back to a secondary provider or model. Two details separate a dependable implementation from a nominal one:

  • Idempotence and streaming. A retry after a stream has started delivering tokens must either be suppressed or restart cleanly, otherwise the client sees duplicated output. Verify how the proxy behaves on mid-stream failure.
  • Capability matching. A fallback model must support the features the request uses, such as tool calling, structured output, or a given context window. Fallback chains should be defined among compatible models only.

Features that matter when you evaluate a proxy

Load balancing

When you run several deployments of the same model, or several keys with separate rate limits, the proxy can spread traffic across them. Weighted round-robin is the baseline; latency-aware or least-busy selection is better under uneven load. Provider-isolated queues are a useful property, because backpressure from one throttled provider then does not degrade traffic to the others.

Features that matter when you evaluate a proxy

Keys, permissions, and data handling

Treat the proxy as a credential boundary. Upstream provider keys should be stored encrypted and never returned to clients, while issued virtual keys carry their own model allow-list, budget, and expiry. Review three questions before deployment:

  • Does the proxy log prompts and completions by default, and can that be disabled or redacted per key?
  • Where does it run, and does traffic leave the network boundary you committed to in your own privacy terms?
  • Can you scope a key to one team, environment, or customer so that one leaked credential has a limited blast radius?

Because prompts frequently contain customer data, a proxy that logs full payloads becomes a data store in its own right and should be governed like one.

Features that matter when you evaluate a proxy

Usage limits and cost control

Cost control is where a central point pays for itself. Because every request passes through one place, the proxy can attribute tokens to a team, feature, or customer, enforce a hard monthly ceiling, and alert before the ceiling is reached. Per-key budgets and per-minute token limits stop a runaway loop from exhausting an account overnight. This matters more with agents, which make many model calls per task. Our analysis of why Claude Code gets expensive and what reduces the bill shows how repeated context and tool loops multiply token spend.

Features that matter when you evaluate a proxy

Observability

At minimum, record per request: timestamp, caller identity, provider and model, input and output tokens, latency, status, and computed cost. Add a trace identifier so a user-facing failure can be followed to the upstream call. Exporting this telemetry to your existing monitoring stack is preferable to adopting a separate dashboard nobody checks.

Architecture trade-offs before you deploy

A proxy sits on the critical path of every model call, so its design determines your availability. One independent multi-provider gateway design document recommends separating a stateless, horizontally scalable data plane from a control plane that holds model metadata, routing rules, tenant budgets, key storage, and the cost ledger. The same document recommends caching control-plane facts, including pricing, capabilities, routing rules, and rate-limit configuration, on the gateway nodes instead of fetching them synchronously on each request, so a control-plane outage does not halt the hot path.

Translated into an evaluation checklist:

ConcernWhat to verify
Added latencyMeasure p50 and p99 overhead with your payload sizes and streaming enabled, not the vendor’s idle benchmark.
Single point of failureRun at least two instances behind a load balancer; confirm the proxy starts and serves from cached configuration if its database is unavailable.
Budget accuracyDecide whether counters are strict or eventually consistent; concurrent nodes can briefly overshoot a limit.
Provider feature driftConfirm how quickly new provider parameters, such as reasoning settings, pass through without waiting for a proxy release.
Self-hosted vs managedSelf-hosting gives data control and costs operations time; a managed service reverses that trade.
Exit costPrefer open standards and an open-source core so that leaving does not mean rewriting every client.

The common failure modes are predictable: a proxy that normalizes everything to the lowest common denominator and hides provider-specific features, a shared master key that makes attribution impossible, and a fallback chain nobody tested until the day the primary provider failed.

Why agents need more than a proxy

Searches for an LLM gateway for agents reflect a real gap. A proxy handles a stateless call: prompt in, completion out. An agent product is different in kind. A single user task can spawn a long-running session that reads uploaded files, executes shell commands, edits a workspace, calls plugins, and keeps memory between turns. None of that exists at the model API level, so a proxy in front of the models leaves the following concerns with you:

  • Session lifecycle: creating, resuming, and expiring agent sessions, and persisting session storage across restarts.
  • Environment provisioning: a sandbox with the right runtime, dependencies, and permissions per task or per customer.
  • File handling: getting inputs into the workspace and outputs back out reliably.
  • Harness differences: each agent harness, such as a coding agent from one lab or another, has its own protocol, configuration, and event stream.
  • Evaluation: knowing which harness and model pairing delivers acceptable quality at an acceptable price for your task.

The harness and the model are separable choices, and treating them as one is a frequent source of lock-in. We discuss that separation in agent harness vs model, and the layers around it in the AI agent stack overview. A proxy operates at the model layer; the moves that matter for agent products happen one layer up, which we describe in from model layer to harness layer.

Our perspective: put the harness behind the API, not just the model

We build HarnessRouter because we observed that product teams who adopt a proxy solve the first integration problem and then meet a second one. Their model calls are tidy, yet the agent they ship is wired to one harness with its own backend, its own session handling, and its own deployment path. Replacing that harness, or running two side by side to compare them, becomes a project instead of a configuration change.

Our position follows from that. The unit of portability for an agent product is the harness plus the model, not the model alone. HarnessRouter is a unified interface for agent harnesses, available as the open-source Community Edition and the managed HarnessRouter Cloud. It exposes Codex, Claude Code, Hermes, and other supported harnesses through one Agent API, so a product team manages sessions, files, tools and skills, and execution environments through a single contract, and benchmarks harness and model combinations against its own tasks before committing. Where a proxy answers “which provider receives this completion request,” the Agent API answers “which agent runs this task, in which environment, with which state.” We consider both questions necessary, and we consider the second the one that determines whether an agent product can be operated at scale.

HarnessRouter supports self-hosted and managed deployments, so a team can start on the open-source Community Edition and move to the cloud service, or the reverse, without changing its integration. Portability of this kind is the practical test of the term we use in our note on AI agent portability.

Choosing between a proxy and an agent API

A short decision path:

  • You call models for completions, summaries, or classification. A proxy or a gateway is the right layer. Prioritize fallback, key scoping, and cost attribution.
  • You choose between models per request. Add a router, and ground the choice in your own measurements. Our guide to model evals explains how to compare models on your use case instead of public leaderboards.
  • You ship an agent that executes work. You need session management, sandboxed environments, file handling, and a harness you can swap. A proxy alone will not provide these.
  • You are unsure. Start with the narrowest layer that solves today’s failure, but choose tools built on open standards so that moving up a layer does not force a rewrite. The first-run problems teams meet when wiring a new model into a product are cataloged in our piece on system one model integration pitfalls.

Running agent harnesses through one API

HarnessRouter provides one Agent API for complete agent harnesses, including Codex, Claude Code, Hermes, and other supported harnesses. The API covers session and file management, tool and skill use, isolated sandboxed execution, and execution traces for comparing harness and model combinations on your own tasks. You can inspect and self-host the Community Edition, or use the fully managed HarnessRouter Cloud, which exposes the same API contract.

Plans, usage fees, and current terms are listed on the pricing page; confirm them there before you plan a budget. To see the whole product, start from the [HarnessRouter home page](/).

Sources

FAQ

Frequently asked questions

Is an LLM proxy the same as an LLM gateway?
Not exactly, though the terms overlap in vendor marketing. A proxy focuses on transport and provider normalization, while a gateway adds identity-aware policy such as per-team budgets, quotas, and audit logs. Many products combine both, so evaluate by the responsibilities you need rather than the label.
Can I self-host an LLM proxy?
Yes, and several open-source proxies exist for exactly this. Self-hosting keeps prompts and keys inside your own network, but you then operate the instances, upgrades, and failover. If you need agent sessions and environments as well, the HarnessRouter Community Edition is open source and can be self-hosted.
Does a proxy add latency?
Yes, since every request takes an extra network hop and some processing. The overhead is usually small relative to model inference time, but measure it with your real payloads and streaming enabled, and look at tail latency instead of the average.
What happens if the proxy goes down?
It becomes an outage for every application behind it unless you plan for that. Run multiple instances, keep a stateless data plane, and cache configuration on each node so traffic continues if the control plane is unavailable. Test the failure path before you depend on it.
Do AI agents work through a standard LLM proxy?
They can use it for model calls, but the proxy does not manage agent sessions, workspaces, files, or the harness itself. Teams building agent products typically add a layer that handles those concerns, such as an agent API in front of the harnesses.

→Next

Get your API key in the quickstart

Open the HarnessRouter quickstart and create an API key for your application.