adding-models

Adding Models

This skill guides you through adding a new LLM model to Letta Code.

Quick Reference

Key files:

• src/models.json - Model definitions (required)
• .github/workflows/ci.yml - CI test matrix (optional)
• src/tools/manager.ts - Toolset detection logic (rarely needed)

Workflow

Step 1: Find Valid Model Handles

Query the Letta API to see available models:

curl -s https://api.letta.com/v1/models/ | jq '.[] | .handle'

Or filter by provider:

curl -s https://api.letta.com/v1/models/ | jq '.[] | select(.handle | startswith("google_ai/")) | .handle'

Common provider prefixes:

• anthropic/ - Claude models
• openai/ - GPT models
• google_ai/ - Gemini models
• google_vertex/ - Vertex AI
• openrouter/ - Various providers

Step 2: Add to models.json

Add an entry to src/models.json:

{
  "id": "model-shortname",
  "handle": "provider/model-name",
  "label": "Human Readable Name",
  "description": "Brief description of the model",
  "isFeatured": true,  // Optional: shows in featured list
  "updateArgs": {
    "context_window": 180000,
    "temperature": 1.0  // Optional: provider-specific settings
  }
}

Field reference:

• id: Short identifier used with --model flag (e.g., gemini-3-flash)
• handle: Full provider/model path from the API (e.g., google_ai/gemini-3-flash-preview)
• label: Display name in model selector
• description: Brief description shown in selector
• isFeatured: If true, appears in featured models section
• updateArgs: Model-specific configuration (context window, temperature, reasoning settings, etc.)

Provider prefixes:

• anthropic/ - Anthropic (Claude models)
• openai/ - OpenAI (GPT models)
• google_ai/ - Google AI (Gemini models)
• google_vertex/ - Google Vertex AI
• openrouter/ - OpenRouter (various providers)

Step 3: Test the Model

Test with headless mode:

bun run src/index.ts --new --model <model-id> -p "hi, what model are you?"

Example:

bun run src/index.ts --new --model gemini-3-flash -p "hi, what model are you?"

Step 4: Add to CI Test Matrix (Optional)

To include the model in automated testing, add it to .github/workflows/ci.yml:

# Find the headless job matrix around line 122
model: [gpt-5-minimal, gpt-4.1, sonnet-4.5, gemini-pro, your-new-model, glm-4.6, haiku]

Toolset Detection

Models are automatically assigned toolsets based on provider:

• openai/* → codex toolset
• google_ai/* or google_vertex/* → gemini toolset
• Others → default toolset

This is handled by isGeminiModel() and isOpenAIModel() in src/tools/manager.ts. You typically don't need to modify this unless adding a new provider.

Common Issues

"Handle not found" error: The model handle is incorrect. Run the validation script to see valid handles.

Model works but wrong toolset: Check src/tools/manager.ts to ensure the provider prefix is recognized.