Model Routing

Model routing decides which provider serves each model Amp uses. By default Amp serves every model and bills your Amp credits. You can add your own connections so that some or all models go through your own API keys, subscriptions, or gateways instead, and your provider bills you directly.

Manage your connections in Model Routing in your personal settings. Workspace admins manage shared connections for every member in Workspace Model Routing. The same operations are available from the CLI with amp config model-providers and from Puck, which can list, add, test, reorder, and edit your connections when you ask.

Tip: We strongly recommend letting Amp or Puck configure your model routing for you, since they can try a configuration, test it, and fix it in a tight loop, which saves you a lot of time compared with working through the details by hand.

Connections

A connection is one credential plus its settings. There are three kinds:

  • API keys for a single provider, such as Anthropic, Google AI Studio, Meta AI, OpenAI, or xAI. Usage bills to your account with that provider. Create a Gemini API key in Google AI Studio, importing your Google Cloud project first if it does not appear. This connects to the Gemini API, not Vertex. The separate Google Cloud Agent Platform connection uses workload identity for Vertex instead of an API key.
  • Subscriptions, such as a ChatGPT or đť•Ź Premium+/SuperGrok subscription. You sign in through your browser, and usage counts against the plan’s limits. See Use a ChatGPT Subscription.
  • AI model routers and gateways, such as OpenRouter, Vercel AI Gateway, Cloudflare AI Gateway, Ollama Cloud, OpenCode Go, and any OpenAI- or Anthropic-compatible endpoint through a Custom URL connection. These can serve models from many providers through one credential. AI model routers and gateways are experimental and in early access for Megawatt, Gigawatt, and Enterprise customers only. We will roll them out to everyone soon.

The Add menu in Model Routing lists the connection types available to you. Personal connections apply to your own threads. Workspace connections apply to every member’s threads, and Enterprise workspace admins can forbid personal connections so that only the workspace’s apply. See Workspaces.

Each connection has a Check Access button that verifies the credential with the provider. From the CLI, amp config model-providers test <connection-id> does the same, and amp config model-providers check-access --provider-model <provider/model> runs one short inference and reports which connection actually served it.

Precedence

For each model, Amp tries your connections in order and uses the first active one whose model mapping includes that model. Anything no connection serves is served by Amp.

The order is:

  1. Your personal connections, from top to bottom as listed in Model Routing.
  2. Your workspace’s connections, from top to bottom.
  3. Amp.

Within a list, the order is the connection’s priority: 0 is tried first. Drag a connection by its handle in Model Routing to move it, or set its priority directly:

amp config model-providers list
amp config model-providers set-priority <connection-id> 0

Setting a priority that another connection already has moves that connection and the ones after it down one place, so 0 always means “try this connection first”. list and list --json show the current priority of each connection.

Two connections often cover the same model, for example a ChatGPT subscription and an OpenRouter router that both include openai/gpt-5.6-sol. The one higher in the list wins. To send only some models to a lower connection, exclude them from the higher connection’s model mapping rather than reordering.

The routing graph below the connection list shows which connection serves each model, so you can confirm the result after changing the order or a mapping.

Activate and Deactivate

Inactive connections are skipped during routing but keep their settings, so you can switch a connection off and on without re-entering its key. Expand the connection in Model Routing and use Activate or Deactivate, or:

amp config model-providers activate <connection-id>
amp config model-providers deactivate <connection-id>

Multiple API keys for the same provider can be active at once. Model mappings and priority determine which key serves each model. AI model routers and Custom URL connections can also be active together.

Subscriptions allow only one active connection of each subscription type per user. For example, activating a ChatGPT subscription deactivates your other active ChatGPT subscription, but leaves your OpenAI API keys active.

Deactivating a subscription can cost more than it saves, because Amp then serves those models with your credits. The CLI asks for --yes before it deactivates a subscription.

Model Mappings

A model mapping controls which models a connection serves and, for routers and Custom URLs, what model ID the provider receives. Leave it empty to use the connection type’s default: for most types, every model the provider supports. Google Cloud Agent Platform and Amazon Bedrock connections serve no models until you choose some.

Write one pattern per line, using Amp’s canonical model IDs in provider/model form. The Models picker in the connection form searches the catalog and inserts an ID for you.

*/*                                   # include every model
-anthropic/*                          # then exclude all Anthropic models
anthropic/claude-fable-5              # but re-include this one
moonshotai/kimi-k3 -> kimi-k3-turbo   # include, and send kimi-k3-turbo to the provider
  • # starts a comment; blank lines are ignored.
  • * is allowed only at the start or end of a pattern: openai/*, *-mini, or */*.
  • A leading - excludes matching models.
  • The last matching line wins. Models that match no line are not served by the connection.
  • An exact include line may end with -> providerModelID to override the model ID sent to the provider. The line still takes part in matching. Arrows are not allowed on wildcard or exclude lines. Without an arrow, the connection type’s default provider model ID is used.

For Amazon Bedrock, wildcard matches apply only when Amp knows the Bedrock model ID. Otherwise, Amp skips that connection and follows the remaining routing order, which may use another provider or Amp credits. An exact model selection still reports an error if its Bedrock ID is unknown. Use model -> bedrock-model-or-inference-profile-id to supply the ID yourself. Once Amp adds a model’s Bedrock ID, matching wildcards automatically route it through Bedrock.

From the CLI, pass the same patterns comma- or newline-separated with --model-mapping, or --clear-model-mapping to return to the default:

amp config model-providers edit-router <connection-id> --model-mapping "*/*,-openai/gpt-5.4"
amp config model-providers edit-key <connection-id> --model-mapping "anthropic/claude-opus-4-6"

The connection form and show report nonblocking warnings about a mapping, for example a line that names a model the provider does not offer or an option the provider requires for it. A warning does not stop the connection from being saved or used.

Custom URL Connections

A Custom URL connection speaks one of four API formats. Enter the base URL, and Amp appends the API path for the format:

  • chat-completions (OpenAI Chat Completions API, the default) sends requests to <base URL>/chat/completions.
  • responses (OpenAI Responses API) sends requests to <base URL>/responses.
  • anthropic-messages (Anthropic Messages API) sends requests to <base URL>/v1/messages. A base URL that already ends in /v1 is accepted and not doubled.
  • google-genai (Google Generative AI) sends native Gemini requests to <base URL>/models/<model>:streamGenerateContent?alt=sse. Use https://generativelanguage.googleapis.com/v1beta for an AI Studio key. For a Vertex API key, use https://aiplatform.googleapis.com/v1; Amp sends those requests to <base URL>/publishers/google/models/<model>:streamGenerateContent?alt=sse. This format routes Gemini models only by default. Google Cloud Agent Platform still uses workload identity, not an API key, and can also serve Claude models.

For example, a base URL of https://api.example.com/v1 with chat-completions sends requests to https://api.example.com/v1/chat/completions, while https://api.example.com with anthropic-messages sends them to https://api.example.com/v1/messages. The connection form shows the exact request URL as you type. Amp warns if the base URL already contains the API path.

The key is sent as Authorization: Bearer <key> for the OpenAI and Anthropic formats. Google Generative AI sends it as x-goog-api-key by default. To use a bearer token instead, enter Bearer <token> in the API key field. Amp then sends only Authorization: Bearer <token>, not an API-key header. Use the Headers settings or --headers in the CLI when a provider needs additional headers. Query Parameters are available for the other formats, but not Google Generative AI.

For a private Gemini model on a Vertex endpoint, choose google-genai, enter the base URL including the API version, and map the Gemini model your agent uses to the full endpoint resource:

google-vertex/gemini-3-flash-preview -> projects/your-project/locations/us-east5/endpoints/123

With the base URL https://us-east5-aiplatform.googleapis.com/v1, this sends requests to https://us-east5-aiplatform.googleapis.com/v1/projects/your-project/locations/us-east5/endpoints/123:streamGenerateContent?alt=sse. Custom HTTPS hosts work too, provided they are reachable from Amp and implement the same Gemini API. Full resource paths beginning with projects/ or publishers/ are preserved. A mapping changes where that Gemini model runs; it does not change the model selected by your agent.

Store the bearer token in the connection’s API key field, not in thread settings or custom headers. Amp uses the supplied credential, not its own Google credentials. You must replace the token when it expires; Custom URL connections do not refresh OAuth tokens.

Check Access on a Custom URL connection lists the provider’s models when the mapping is broad, and sends a one-token request for the mapped model when the mapping names exactly one model. For Google Generative AI it sends a one-token Gemini request rather than listing models. Providers that respond to an invalid key with an HTTP 200 body containing an error are reported as failures with the provider’s message.