Providers
Connect a model provider — the models your agents think with, datasets embed with, and scanned documents are read with.
A provider connection links Compass to a model service. Most often it's the "brain" an agent reasons with, but providers also supply the embedding models that datasets and the Embeddings component use, and the OCR that reads scanned documents.
Available providers
| Provider | What it's for | What it needs |
|---|---|---|
| Anthropic | Claude models via the Anthropic API. Generation. | An API key. Optionally a custom Base url (under Advanced). |
| OpenAI | OpenAI models, or any OpenAI-compatible API. Generation and embedding. | An API key. Optionally a custom Base url (under Advanced) for an OpenAI-compatible server. |
| LM Studio | Local models served through LM Studio's OpenAI-compatible API. Generation and embedding. | The server's Base url, and a value in Api key (any placeholder, if your server doesn't check keys). |
| Azure Document Intelligence | Reading scanned documents — OCR with layout, tables, and reading order. OCR only. | Your resource's Endpoint (for example https://my-di.cognitiveservices.azure.com) and its API key. |
LM Studio must be reachable from Compass
The LM Studio server has to be reachable from where Compass runs, not just from
your browser. A server on localhost on your laptop won't work with a hosted
Compass — expose it on an address Compass can reach.
One connection, one model
A provider connection runs exactly one model, chosen when you create it. Agents, components, and datasets pick a connection, and the connection carries the model — there's no separate model choice to make.
To use another model, create another connection. Keeping separate connections for separate jobs is the intended pattern — for example, one for your production model, one for a fast, inexpensive model used while testing, and one for an embedding model your datasets index with.
Connecting a provider
Start a new provider connection
Under Studio → Connections, click the provider's card, then New connection.
Name it
Enter a Connection name, like "Anthropic — Production", plus any settings the provider asks for (LM Studio's Base url, Azure's Endpoint).
(Optional) Route through a gateway
Under Gateway, choose a gateway to proxy this connection's calls through, or leave it on No gateway (direct connection).
Authenticate
Enter the Api key and click Continue. Compass uses the key to fetch the
models your account can reach; if that fails, the step says so and stays open.
(Azure Document Intelligence offers a fixed pair of models — prebuilt-layout,
which keeps headings, tables, and reading order, and the cheaper prebuilt-read —
and its key is checked when you save.)
Choose the model
Pick the model this connection runs from the list, grouped under Generation, Embedding, and OCR.
Spend & cost
Review pricing and, optionally, set a budget (see below).
Create
Click Create connection. Compass checks the connection live; if the provider can't be reached, the save fails with the reason.
What saving records
Every time a provider connection is saved, Compass checks it against the provider and records what its model can do:
- Capability — Generation, Embedding, or OCR, shown as a badge on
the connection. For an embedding model, the vector size is recorded too (for
example
3072d). - Reasoning support — whether the model can reason before answering, and at which effort levels. This is what makes the Reasoning control appear on agents and in chat.
- Sampling support — whether the model accepts temperature and top-P. Some newer models don't, and Compass greys those settings out rather than letting a request fail.
Pickers use what was recorded. Agents and Compass Chat only offer Generation connections; datasets and the Embeddings component only offer Embedding; the Document Parser's OCR setting only offers OCR. If a connection doesn't appear where you expect, check its badge.
Spend & cost
The last step of the form sets up cost tracking and an optional budget for the agent model calls that run through the connection.
- Token costs — per-million-token rates for input and output. They're prefilled from the model's standard price; edit them only to override, for example for a self-hosted or fine-tuned model. Reset to standard undoes an override. A model with no standard price shows a prompt to enter rates — until you do, its executions show no cost and spend limits can't count it.
- Spend limit — a Budget (USD), a Period (per day, per month, last 30 days, or lifetime), and When exceeded: Block refuses new work, Alert only marks the overage. Leave the budget blank for no limit. Setting a spend limit takes an Admin role. See Spend limits.
A connection limit is the universal circuit breaker for agents: it covers agent and chat model calls — deployed, test, and scheduled alike — because all of them reach the model through the connection. Block stops the next agent step that would use it. Embedding and OCR calls aren't counted against it.
Reasoning and sampling
For models that support it, agents and chat can turn on reasoning and choose an effort level. The levels come from the provider:
| Provider | Levels |
|---|---|
| Anthropic | Low, Medium, High, Extra high — on models that support adaptive thinking. |
| OpenAI | Minimal, Low, Medium, High — on reasoning models. Some models always reason, and show Always on. |
| LM Studio | None. |
See Building an agent for how these appear in the builder.
Editing and rotating keys
To rotate an API key, edit the connection, enter the new key, and save. When you edit a provider connection you re-enter its key — the Authentication step uses it to list the models again. Saving re-checks the model and re-records its capabilities.
Because every agent points at the connection rather than at a raw key, the change takes effect everywhere at once, including in live deployments.