> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Model schemas
> Add built-in and custom models in AgentMark
You can add models to your AgentMark project in two ways: pull pre-configured models from supported providers using the CLI, or define custom model schemas with full control over settings and pricing.
The model dropdown in the Dashboard prompt editor draws its options from the `builtInModels` and `modelSchemas` fields in your `agentmark.json`. If the dropdown is empty, your config has no models yet; add some with the steps below and they'll appear. New projects include one model (`openai/gpt-5.5`) by default.
## Pulling built-in models
Use the `pull-models` command to add models to your `agentmark.json`:
```bash theme={null}
agentmark pull-models
```
Run interactively, it:
1. Shows you the available providers
2. Lets you select which models to add
3. Updates `builtInModels` in your `agentmark.json`
For scripts, CI, or coding agents, skip the picker with flags. List the available IDs, then add the ones you want:
```bash theme={null}
# Print a provider's model IDs as JSON (no changes, no auth):
agentmark pull-models --provider anthropic --list
# Add specific models non-interactively:
agentmark pull-models --provider anthropic --models anthropic/claude-sonnet-4-5,anthropic/claude-opus-4-5
```
The CLI writes each pulled entry in `provider/model` form. For example, selecting OpenAI's `gpt-5` writes `"openai/gpt-5"` to `builtInModels`, and selecting Ollama's `llama3.1` writes `"ollama/llama3.1"`. The tables below list the model IDs without the provider prefix for readability.
The full set of models comes from AgentMark's [model registry](https://github.com/agentmark-ai/agentmark/tree/main/packages/model-registry) (sourced from LiteLLM and OpenRouter). Run `pull-models --provider --list` to print the authoritative list for each provider as JSON. The tables below highlight a handful of commonly used IDs.
### Supported providers
AgentMark ships provider labels for: OpenAI, Anthropic, Google (including Vertex AI), xAI Grok, Groq, Cohere, Mistral, DeepSeek, Together AI, Ollama, Fireworks, AWS Bedrock, Azure OpenAI, and Perplexity. The tabs below show a subset with example IDs.
**Language models:** `gpt-5`, `gpt-5-mini`, `gpt-4.1`, `o3`, `o4-mini`, and more
**Image models:** `dall-e-3`, `dall-e-2`
**Speech models:** `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
**Language models:** `claude-4-opus-20250514`, `claude-4-sonnet-20250514`, `claude-3-7-sonnet-20250219`, `claude-3-opus-20240229`, `claude-3-haiku-20240307`, plus `*-latest` aliases, and more.
The registry contains both dated IDs (e.g. `claude-4-opus-20250514`) and bare IDs (e.g. `claude-opus-4`, `claude-3-haiku`, `claude-3.5-sonnet`); if a bare name isn't found, use the dated ID or `-latest` alias instead.
**Language models:** `gemini-2.0-flash`, `gemini-2.5-pro`, and more
**Language models:** `codellama`, `deepseek-r1`, `gemma`, `gemma2`, `llama3.1`, `llama3.2`, `llava`, `mistral`, `mistral-small`, `mistral-small3.1`, `qwen`, `qwen2.5`, `tinyllama`
**Language models:** `grok-3`, `grok-3-mini`, `grok-3-fast-beta`, `grok-3-fast-latest`, `grok-2-vision`, and more
**Language models:** `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `openai/gpt-oss-120b`, `moonshotai/kimi-k2-instruct-0905`, `qwen/qwen3-32b`, `meta-llama/llama-4-scout-17b-16e-instruct`, and more
Pulled models land in `builtInModels`, an allowlist the client enforces at render time. At call time, the code that calls your SDK (your call site or [executor](/getting-started/client-setup#connect-your-sdk)) maps each prompt's `model_name` to the model ID your SDK expects. See [Model names vs provider model IDs](/getting-started/client-setup#model-names-vs-provider-model-ids).
## Custom model schemas
For models not covered by the built-in providers, or when you need custom settings and pricing, define model schemas in your `agentmark.json` under `modelSchemas`.
### Basic structure
Each model schema includes:
* **label**: Display name shown in the AgentMark Dashboard prompt editor
* **cost**: Pricing configuration for cost tracking
* **settings**: Configurable parameters with UI controls
```json theme={null}
{
"modelSchemas": {
"my-custom-model": {
"label": "My Custom Model",
"cost": {
"inputCost": 0.01,
"outputCost": 0.03,
"unitScale": 1000000
},
"settings": {}
}
}
}
```
### Cost configuration
The `cost` object defines pricing for cost tracking:
| Property | Description |
| ------------ | ---------------------------------------------------------------------------- |
| `inputCost` | Cost per unit for input tokens (USD) |
| `outputCost` | Cost per unit for output tokens (USD) |
| `unitScale` | Number of tokens per unit (for example, `1000000` = cost per million tokens) |
```json theme={null}
"cost": {
"inputCost": 0.01,
"outputCost": 0.03,
"unitScale": 1000000
}
```
This means $0.01 per million input tokens and $0.03 per million output tokens.
### Settings configuration
Settings define configurable parameters that appear in the Dashboard prompt editor. Each setting has:
| Property | Description |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | Display name shown in the Dashboard |
| `order` | Sort order (ascending, so lower values appear first) |
| `default` | Default value |
| `type` | One of `"slider"` or `"number"` (numeric, paired with `ui: "slider"`), or `"string"` (for select, imageSize, and aspectRatio controls) |
| `ui` | Which control to render: `slider`, `select`, `imageSize`, or `aspectRatio` |
If you omit `ui`, the Dashboard editor infers the control from `type` (for example, `number` renders a slider, and `string` with an `options` array renders a select). A `ui` value outside the supported set renders as "unsupported".
The available controls are:
For numeric values with a range:
```json theme={null}
"temperature": {
"label": "Temperature",
"order": 1,
"default": 0.7,
"minimum": 0,
"maximum": 2,
"multipleOf": 0.1,
"type": "slider",
"ui": "slider"
}
```
For dropdown selection, use `type: "string"` with `ui: "select"` and an `options` array:
```json theme={null}
"response_format": {
"label": "Response format",
"order": 3,
"default": "json",
"type": "string",
"ui": "select",
"options": [
{ "label": "JSON", "value": "json" },
{ "label": "Text", "value": "text" }
]
}
```
Specialized controls for image generation models:
```json theme={null}
"image_size": {
"label": "Image size",
"order": 4,
"default": "1024x1024",
"type": "string",
"ui": "imageSize"
}
```
```json theme={null}
"aspect_ratio": {
"label": "Aspect ratio",
"order": 5,
"default": "16:9",
"type": "string",
"ui": "aspectRatio"
}
```
### Complete example
Here's a full example with a text model and an image model:
```json agentmark.json theme={null}
{
"$schema": "https://raw.githubusercontent.com/agentmark-ai/agentmark/refs/heads/main/packages/cli/agentmark.schema.json",
"version": "2.0.0",
"agentmarkPath": ".",
"modelSchemas": {
"gpt-4-custom": {
"label": "GPT-4 Custom",
"cost": {
"inputCost": 0.03,
"outputCost": 0.06,
"unitScale": 1000000
},
"settings": {
"temperature": {
"label": "Temperature",
"order": 1,
"default": 0.7,
"minimum": 0,
"maximum": 2,
"multipleOf": 0.1,
"type": "slider",
"ui": "slider"
},
"max_tokens": {
"label": "Max tokens",
"order": 2,
"default": 2048,
"minimum": 1,
"maximum": 8192,
"multipleOf": 1,
"type": "slider",
"ui": "slider"
},
"response_format": {
"label": "Response format",
"order": 3,
"default": "text",
"type": "string",
"ui": "select",
"options": [
{ "label": "Text", "value": "text" },
{ "label": "JSON", "value": "json" },
{ "label": "JSON Schema", "value": "json_schema" }
]
}
}
},
"dall-e-3": {
"label": "DALL-E 3",
"cost": {
"inputCost": 0.04,
"outputCost": 0,
"unitScale": 1
},
"settings": {
"image_size": {
"label": "Image size",
"order": 1,
"default": "1024x1024",
"type": "string",
"ui": "imageSize"
},
"quality": {
"label": "Quality",
"order": 2,
"default": "standard",
"type": "string",
"ui": "select",
"options": [
{ "label": "Standard", "value": "standard" },
{ "label": "HD", "value": "hd" }
]
}
}
}
}
}
```
## Best practices
1. **Use descriptive labels:** make it clear what each setting does in the Dashboard.
2. **Set appropriate ranges:** define minimum and maximum values that make sense for your model.
3. **Order settings logically:** lower `order` values appear first in the prompt editor.
4. **Provide sensible defaults:** choose default values that work well for most use cases.
5. **Document costs accurately:** match the cost configuration to your provider's pricing.
Have questions?
Reach out any time: