# Add and manage Models

> Create stable Agent-facing Models from provider-billed Gateways while keeping displayed pricing separate from Constal charges.

A Model is the stable Resource an Agent binds. It records the provider model ID, technical limits, defaults, an immutable pricing snapshot, and the exact Gateway used for transport. Provider Credentials stay on the Gateway.

## Before you begin {#before-you-begin}

Install a tenant-billed [Gateway](/docs/resources/gateways.md). Its provider account receives the upstream bill. Platform Models provided through Constal Gateway are already available and do not use this flow.

## Add a Model {#add-a-model}

1. Open **Resources → Models** and choose **Add Model**.
2. Choose a Gateway. The picker only shows tenant-billed model Gateways in the current namespace.
3. Choose an advertised model. If the Gateway does not publish a catalog, choose **Enter manually**.
4. Review or enter the provider model ID, context window, maximum output, and provider pricing.
5. Give the Model a stable lowercase name and choose **Add Model**.

For an advertised model, Constal reloads the offer from the immutable Gateway package during admission. The browser cannot substitute different limits or prices. Manual entry is intended for account-specific catalogs and Gateways without standardized discovery.

## Pricing is information, charging is policy {#pricing-and-charging}

The Model page shows nominal provider prices in USD per million tokens:

```text
IN / OUT / CACHE IN / CACHE WRITE
$1.00 / $5.00 / $0.10 / $1.25
```

For a tenant-billed Gateway, that snapshot is for operator visibility. The provider charges the account connected to the Gateway; Constal's platform model charge is `$0`. The server creates the Model with no platform charge table, and the runtime rejects a payer or accounting mismatch before dispatch.

If the provider returns an exact request cost, Analytics may record it as tracked upstream cost. Tracked cost is not a Constal charge and does not consume the Run's Constal model budget.

## Bind it to an Agent {#bind-it-to-an-agent}

Bind the logical Model Resource in the Agent manifest:

```json constal.agent.json
{
  "schemaVersion": 2,
  "kind": "agent",
  "id": "researcher",
  "namespace": "default",
  "version": "1.0.0",
  "entry": "agent.ts",
  "mode": "script",
  "bindings": {
    "model": "crn:constal:production:YOUR_TENANT:default:model/research-model"
  },
  "policies": [],
  "tools": [],
  "limits": { "maxRunMicroUsd": 0, "maxTurns": 40 },
  "expectedCurrentDeploymentRevision": null
}
```

Agent code continues to use the logical binding name:

```ts agent.ts
import { agent } from "@constal/sdk";

export default agent({
  id: "researcher", version: "1.0.0", model: "model",
  async onMessage(message, ctx) {
    return ctx.turn({ system: "Research accurately.", objective: message });
  },
});
```

The Agent calls `model/research-model`. Admission pins the logical Model, its exact Gateway, accepted Credentials, and Policy into the Run. Agent code never receives the provider Credential.

## Verify {#verify}

Open the Model detail page and confirm the model ID, Gateway, context window, output limit, and pricing snapshot. Start a controlled Run and inspect its bindings and journal. The logical Model should remain the called Resource, while the resolved Gateway appears in dispatch evidence and the settled platform charge remains zero.

Use [Gateways and Models](/docs/resources/gateways-and-models.md) for the architecture and [scoped bindings](/docs/credentials/scoped-bindings) when a shared Agent needs a different Gateway for each customer or principal.