agent-zero/plugins/_model_config

Model Configuration

Manage which models Agent Zero uses for chat, utility, and embeddings, with support for scoped overrides and reusable presets.

What It Does

This plugin centralizes model selection and model-related settings for the application. It provides helpers and APIs for:

• selecting chat, utility, and embedding models
• reading and saving model presets
• checking for missing API keys
• allowing optional per-chat model overrides
• resolving config at global, project, agent, and chat scope

Main Behavior

• Scoped configuration
  • Reads plugin config through the standard plugin config system with project and agent overrides.
• Preset management
  • Loads presets from a user file when present and falls back to bundled defaults.
  • Project presets can be stored beside a project's scoped model config.
• Per-chat override
  • Allows a chat context to store a temporary override or preset reference in context data.
• Model object construction
  • Builds ModelConfig objects and the runtime chat, utility, and embedding wrappers used elsewhere in the app.
• API key validation
  • Reports configured providers that still require API keys.

Key Files

• Core helper
  • helpers/model_config.py resolves config, presets, overrides, and runtime model objects.
• APIs
  • api/model_config_get.py
  • api/model_config_set.py
  • api/model_override.py
  • api/model_presets.py
  • api/model_search.py
  • api/api_keys.py
• Hooks
  • hooks.py exposes plugin-level integration hooks.

Configuration Scope

• Settings section: agent
• Per-project config: true
• Per-agent config: true
• Always enabled: true

Project-Scoped Model Config

Projects store copied model settings in the standard scoped plugin path:

/a0/usr/projects/<project>/.a0proj/plugins/_model_config/config.json

Project-only presets live beside that config:

/a0/usr/projects/<project>/.a0proj/plugins/_model_config/presets.yaml

The project preset file uses the same plain YAML list schema as global presets. It does not contain scope metadata:

- name: Research
  chat:
    provider: openrouter
    name: anthropic/claude-sonnet-4.6
    api_base: ""
    ctx_length: 200000
    ctx_history: 0.7
    vision: true
  utility:
    provider: openrouter
    name: openai/gpt-5.4-mini

Preset slots are partial overlays. Missing fields inherit from the current effective config, so a preset can switch only the model identity while preserving tuned context windows, rate limits, and nested kwargs. The utility and embedding slots are optional and only apply when they declare a provider or model name; otherwise those configured models are inherited. Selecting a preset for a project writes the merged result into the project's config.json.

Plugin Metadata

• Name: _model_config
• Title: Model Configuration
• Description: Manages LLM model selection and configuration for chat, utility, and embedding models. Supports per-project and per-agent overrides with optional per-chat model switching.