Skip to main content

Model Specifications

Model specifications define the AI models available to agents. Each specification captures the model's identity, provider, required credentials, and whether it is the default model used when no explicit model is configured.

Overview​

Model IDs follow the format provider:model-name (e.g., bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0, openai:gpt-4.1). This convention makes it easy to identify both the provider and the specific model variant at a glance.

Required Fields​

id (string)​

Unique model identifier in the format provider:model-name. This is the value used to reference the model throughout the system.

id: "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0"
id: "openai:gpt-4.1"
id: "anthropic:claude-opus-4-20250514"

version (string)​

Spec version (currently 0.0.1).

name (string)​

Display name shown in the UI.

name: Bedrock Claude Sonnet 4.5
name: OpenAI GPT-4.1

description (string)​

Short description of the model's characteristics and strengths.

description: Claude Sonnet 4.5 via AWS Bedrock - balanced performance
description: GPT-4.1 by OpenAI - strong general purpose model

provider (string)​

The model provider. Current values: anthropic, bedrock, azure-openai, openai.

provider: bedrock
provider: openai
provider: anthropic
provider: azure-openai

Optional Fields​

default (boolean)​

Whether this model is the system default (default: false). Exactly one model should have default: true. This model is used when an agent spec does not specify a model field, and when no environment override is set.

default: true

required_env_vars (list of strings)​

Environment variables that must be set for the model to be available. The system checks these at runtime to determine model availability.

required_env_vars:
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY
  - AWS_DEFAULT_REGION

Complete Example​

# Copyright (c) 2025-2026 Datalayer, Inc.
# Distributed under the terms of the Modified BSD License.

# AI Model Specification: Bedrock Claude Sonnet 4.5

id: "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0"
version: 0.0.1
name: Bedrock Claude Sonnet 4.5
description: Claude Sonnet 4.5 via AWS Bedrock - balanced performance
provider: bedrock
default: true

required_env_vars:
  - AWS_ACCESS_KEY_ID
  - AWS_SECRET_ACCESS_KEY
  - AWS_DEFAULT_REGION

Model Hierarchy​

Model Specification
├── Identity (id, name, description)
├── Provider (provider)
├── Default Flag (default)
└── Environment (required_env_vars)

Available Models​

Anthropic (Direct API)​

ModelIDDescription
Claude Haiku 3.5anthropic:claude-3-5-haiku-20241022Fast and efficient
Claude Sonnet 4anthropic:claude-sonnet-4-20250514Strong reasoning and coding
Claude Sonnet 4.5anthropic:claude-sonnet-4-5-20250514Balanced performance and speed
Claude Opus 4anthropic:claude-opus-4-20250514Highest capability model

Required env vars: ANTHROPIC_API_KEY

AWS Bedrock​

ModelIDDescription
Claude Haiku 3.5bedrock:us.anthropic.claude-3-5-haiku-20241022-v1:0Fast and efficient
Claude Sonnet 4bedrock:us.anthropic.claude-sonnet-4-20250514-v1:0Strong reasoning
Claude Sonnet 4.5 ⭐bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0Balanced performance (default)
Claude Opus 4bedrock:us.anthropic.claude-opus-4-20250514-v1:0Highest capability
Claude Opus 4.6bedrock:us.anthropic.claude-opus-4-6-v1:0Latest flagship model

Required env vars: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION

Azure OpenAI​

ModelIDDescription
GPT-4.1 Nanoazure-openai:gpt-4.1-nanoSmallest and fastest
GPT-4.1 Miniazure-openai:gpt-4.1-miniCompact version
GPT-4.1azure-openai:gpt-4.1Strong general purpose
GPT-4o Miniazure-openai:gpt-4o-miniCompact enterprise deployment
GPT-4oazure-openai:gpt-4oEnterprise deployment

Required env vars: AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT

OpenAI (Direct API)​

ModelIDDescription
GPT-4.1 Nanoopenai:gpt-4.1-nanoSmallest and fastest
GPT-4.1 Miniopenai:gpt-4.1-miniCompact version of GPT-4.1
GPT-4.1openai:gpt-4.1Strong general purpose model
GPT-4o Miniopenai:gpt-4o-miniCompact and cost-effective
GPT-4oopenai:gpt-4oFast multimodal model
o3 Miniopenai:o3-miniReasoning-focused compact model

Required env vars: OPENAI_API_KEY

Linking Models to Agents​

Agents can specify a model in their YAML spec using the model ID:

# In agent spec
model: "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0"

If an agent does not specify a model field, the system default model (marked with default: true) is used.

Code Generation​

Model specifications are used to generate:

  • Python: AIModels enum, AIModel dataclass, AI_MODEL_CATALOGUE, and DEFAULT_MODEL constant
  • TypeScript: AIModels object, AIModel interface, AI_MODEL_CATALOGUE, and DEFAULT_MODEL export

Run make specs in the agent-runtimes repository to regenerate from the YAML files.

Best Practices​

  1. ID Format: Use the provider:model-name convention
  2. Single Default: Ensure exactly one model has default: true
  3. Environment Variables: Always list all required credentials in required_env_vars
  4. Descriptions: Keep descriptions short — mention the provider, model tier, and key characteristic
  5. Provider Consistency: Use the canonical provider names (anthropic, bedrock, azure-openai, openai)
  6. File Naming: Use kebab-case matching the provider and model name (e.g., bedrock-claude-sonnet-4-5.yaml)

Full Field Coverage​

Required fields:

  • id
  • version
  • name
  • description
  • provider

Common optional fields:

  • default (bool)
  • required_env_vars