Coding agent configuration schema

This reference describes every field in a coding agent configuration. To publish and manage a configuration, see Configure coding agents.

The following configuration uses every supported field. In a real configuration, set only the fields your team needs, and set exactly one model source per agent. Field names match the keys in the JSON editor and the API.

{
  "default_agent": "CODING_AGENT_CLAUDE_CODE",
  "enabled_agents": [
    {
      "agent": "CODING_AGENT_CLAUDE_CODE",
      "config": {
        "models": {
          "model_services": [
            "system.ai.claude-opus-5-5",
            "system.ai.claude-sonnet-4-6",
            "system.ai.claude-haiku-4-5",
            "system.ai.claude-fable-5"
          ]
        },
        "default_models": {
          "default_model": "system.ai.claude-sonnet-4-6",
          "default_opus_model": "system.ai.claude-opus-5-5",
          "default_sonnet_model": "system.ai.claude-sonnet-4-6",
          "default_haiku_model": "system.ai.claude-haiku-4-5",
          "default_fable_model": "system.ai.claude-fable-5"
        },
        "smart_routing": { "enabled": true },
        "http_headers": { "x-team": "platform" },
        "tracing": { "enabled": true },
        "agent_native_settings": {
          "deniedMcpServers": [{ "serverName": "untrusted-server" }]
        }
      }
    },
    {
      "agent": "CODING_AGENT_CODEX",
      "config": {
        "models": {
          "unity_catalog_location": "main.default"
        },
        "default_models": {
          "default_model": "main.default.gpt-6-sol"
        },
        "smart_routing": { "enabled": false },
        "http_headers": {},
        "tracing": { "enabled": false }
      }
    }
  ],
  "mcp_servers": {
    "unity_catalog_location": "system.ai"
  },
  "skills": {
    "names": ["main.team_skills.code_review", "main.team_skills.test_writer"]
  },
  "smart_defaults": {
    "budget_id": "123e4567-e89b-12d3-a456-426614174000",
    "tiers": [
      {
        "spending_percentage": 0.8,
        "recommended_agent": "CODING_AGENT_CODEX",
        "recommended_model": "main.default.glm-5-3"
      }
    ]
  }
}

Top-level fields

Field Type Description
default_agent string (enum) Agent launched on bare ug when no smart-default tier is active. Must appear in enabled_agents. Valid values: CODING_AGENT_CLAUDE_CODE, CODING_AGENT_CODEX. An active smart_defaults tier overrides it.
enabled_agents array of objects The agents available through ug and their per-agent configuration. Each agent can appear at most once. See enabled_agents[].
mcp_servers object MCP servers to make available to the enabled agents. See mcp_servers.
skills object Skills to make available to the enabled agents. See skills.
smart_defaults object Spend-based recommendations that switch the default agent and model as the budget is consumed. See smart_defaults.

enabled_agents

Field Type Description
agent string (enum) The coding agent this entry configures. Valid values: CODING_AGENT_CLAUDE_CODE, CODING_AGENT_CODEX.
config object Per-agent configuration for this agent. See config.

config

Each enabled_agents entry has a config object that sets the per-agent model source, default models, and Unity Gateway features.

Field Type Description
models object The agent's model source. Set exactly one source. See models.
default_models map The default model or models the agent launches. See default_models.
smart_routing object Opts the agent into Smart Routing, where supported. Takes a single enabled boolean.
http_headers map Headers attached to every gateway request from this agent, as key-value string pairs.
tracing object Per-agent client-side tracing. Takes a single enabled boolean.
agent_native_settings object The agent's own settings, which ug writes as-is into the agent's machine-wide managed settings file. Supported for some agents only. See agent_native_settings.

models

models can contain one of the following. For examples, see Choose model sources for each agent.

Field Type Description
model_services array of strings Static list of full Unity Catalog model service names to make available.
model_provider_service string Full Unity Catalog name of a model provider service. All of its models become available.
unity_catalog_location string A catalog and schema (catalog.schema). All model services there that a developer has EXECUTE on become available.

default_models

default_models is a map of default-model keys to model names. default_model sets the overall default for any agent. The per-family keys (default_opus_model, default_sonnet_model, default_haiku_model, and default_fable_model) apply to Claude Code only. Model names are model IDs when the source is a model provider service, or full Unity Catalog model service names otherwise. With a static model_services list, every default must also appear in that list.

Key Applies to Description
default_model All agents Overall default model to launch.
default_opus_model Claude Code only Default for the Opus family.
default_sonnet_model Claude Code only Default for the Sonnet family.
default_haiku_model Claude Code only Default for the Haiku family.
default_fable_model Claude Code only Default for the Fable family.

agent_native_settings

agent_native_settings passes an agent's own managed settings to developers' machines. When a developer runs ug configure in an interactive terminal, ug writes each key into the agent's machine-wide managed settings file, which takes precedence over the developer's own settings for that agent. Keys and values use the agent's own format, so see the agent's documentation for what each setting does.

Only the agents and keys in the following table are accepted. A configuration that sets agent_native_settings for another agent, or uses another key, is rejected when you save it.

Agent Managed settings file Accepted keys Reference
Claude Code /etc/claude-code/managed-settings.json (Linux), /Library/Application Support/ClaudeCode/managed-settings.json (macOS) allowManagedMcpServersOnly, allowedMcpServers, deniedMcpServers, enableAllProjectMcpServers, enabledMcpjsonServers, disabledMcpjsonServers Claude Code managed MCP configuration

If you remove a key, or a developer switches to a workspace whose configuration doesn't set it, ug removes it from the managed settings file the next time it runs, unless someone edited the value by hand after ug wrote it. To remove the settings that ug wrote, run ug revert.

If you set Claude Code's allowedMcpServers, ug adds the MCP servers it registers from this configuration to the list, so they stay available. To block one of them, remove it from mcp_servers.

mcp_servers

mcp_servers can contain one of the following:

Field Type Description
names array of strings Exact Unity Catalog resource names.
unity_catalog_location string A catalog and schema (catalog.schema). Includes every resource under it.

skills

skills can contain one of the following:

Field Type Description
names array of strings Exact Unity Catalog resource names.
unity_catalog_location string A catalog and schema (catalog.schema). Includes every resource under it.

smart_defaults

Field Type Description
budget_id string (UUID) The budget's budget_configuration_id.
tiers array of objects Spend tiers. The highest tier whose threshold is reached applies.

tiers

Each entry in tiers can contain the following:

Field Type Description
spending_percentage number Fraction of the budget (0–1) at which this tier activates. For example, 0.8 is 80%.
recommended_agent string (enum) Agent to switch the default to. Must appear in enabled_agents. Valid values: CODING_AGENT_CLAUDE_CODE, CODING_AGENT_CODEX.
recommended_model string Model to switch the default to while this tier is active.

The API also returns read-only or server-managed fields that you don't set, including name, workspace_id, create_time, created_user_id, update_time, updated_user_id, and retrieved_time.

  • Last updated on