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": "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

config 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.

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.

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