> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model providers

> Understand model roles, provider adapters, tool calls, and request limits.

A model provider supplies inference. A conversation connector receives and sends
messages in Slack, Telegram, SMS or your application. You can change an agent's
model provider without replacing its conversation connections.

## Supported providers

| Provider | Formation adapter | Setup |
| - | - | - |
| OpenRouter | Chat Completions, with native tool calls or a validated text-tool fallback | Connect a key and select models from the catalog. `openrouter/auto` is also available. |
| Ramp Router | Responses API with native tool calls | Connect a key and select an exact model from its credential-scoped catalog. |
| OpenAI / compatible server | Chat Completions with native tool calls | Use OpenAI cloud or configure an OpenAI-compatible endpoint for the Formation process. |

See [OpenAI and self-hosted inference](https://docs.formation.texturehq.com/operations/openai-and-local-models.md) for
endpoint configuration, keyless local servers, supported request features and
limitations. A custom OpenAI endpoint applies to all agents using that adapter
in the deployment; it is not a separate URL per agent. There is no implicit
fallback from an unavailable local server to a cloud provider.

## Credentials and instance defaults

An owner can configure **Instance model defaults**. New agents inherit the
configured provider, its model assignments and its billing credential. An agent
can instead choose a provider and store its own encrypted key, or use that
provider's instance key. The Models page shows the effective configuration.
Switching providers does not transfer one provider's key to another.

Model keys are usage-payer credentials. Inheritance does not share an agent's
Slack identity, GitHub account, tool credentials, conversations or memory.
`OPENROUTER_API_KEY` is a legacy process fallback, not the normal provisioning
path. It applies only on a self-hosted (local authentication) deployment, only to
agents that inherit instance defaults, and only until instance model defaults are
saved; hosted deployments never use it. An unreadable saved credential must be
repaired; it is not silently replaced with another account's credential — not the
instance key, not the process fallback, and not a managed account's key that the
instance no longer uses. When an instance stops being managed by a hosting control
plane, its managed key records are deleted rather than kept as a fallback.

## Model roles

| Role | Use | When unset |
| - | - | - |
| Primary | Main reasoning, tool use and final replies | Effective instance defaults, then the process fallback |
| Fast | Smaller runtime tasks such as classification, titles and compaction | Primary |
| Heartbeat | Background work, including the Dreaming planner | Fast, then primary |

Structured runtime decisions also have a separate configurable decision-provider
path. See [automatic model selection](https://docs.formation.texturehq.com/runtime/adaptive-model-routing.md) for routing,
provider readiness and the relationship between a selected model and the primary
fallback. Choosing a primary model does not enable every optional runtime feature.

## Automatic model selection

Formation can choose a model for a run from the connected provider's catalog under
its routing policy. New agents start with the installation's default, which is
on unless an owner turns it off. The primary model is normally the fallback and
the price ceiling (a family restriction that excludes it substitutes the best
eligible model in that family), and turns use the primary until it is a
concrete model the catalog lists. The Models page exposes the agent's routing
configuration; operators can inspect route decisions. Selection is bounded by
capability and catalog evidence. Sparse catalogs can conservatively keep the
primary model.
Follow [Automatic model selection](https://docs.formation.texturehq.com/runtime/adaptive-model-routing.md) for supported modes,
configuration and limits.

## Tools and failure handling

Model adapters translate the provider-neutral message and tool contract into
the provider's protocol. Formation decides which tools are available, validates their
arguments, executes them and records their observations. A model request alone
is not evidence that an action happened.

OpenRouter can offer the same granted tools through a strict JSON decision
protocol when native tool support is unavailable. Invalid output is rejected;
a bounded repair can be attempted. Ramp Router and OpenAI use native tool calls
and do not provide that text-protocol fallback.

Runs record model calls, requested and resolved models, provider request IDs,
finish reasons and provider-reported token usage. Retry and fallback behavior is
bounded by the run's budget and recovery policy. Tool rounds are budgeted per
run; the short conversation profile is not a universal limit on coding work.
There is no eight-call limit on a single batch: larger batches are validated
before any call runs, then executed sequentially within the run's allowance.
If a batch exceeds the remaining tool-call budget, none of it runs. Formation records
the refusal and tells the model how many calls remain so it can retry a smaller
batch. Rejected calls do not spend the tool-call allowance; model iterations
still bound recovery attempts. When the allowance is exhausted, the run closes
its tools and produces a final status.
See [Agent harness](https://docs.formation.texturehq.com/runtime/agent-harness.md), [egress reliability](https://docs.formation.texturehq.com/runtime/egress-reliability.md)
and [observability](https://docs.formation.texturehq.com/runtime/observability.md).

The implemented adapter contract is in
[`internal/model`](https://github.com/TextureHQ/formation/tree/main/internal/model).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.