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 |
|---|---|---|
| string (enum) | Agent launched on bare |
| array of objects | The agents available through |
| object | MCP servers to make available to the enabled agents. See |
| object | Skills to make available to the enabled agents. See |
| object | Spend-based recommendations that switch the default agent and model as the budget is consumed. See |
enabled_agents
Field | Type | Description |
|---|---|---|
| string (enum) | The coding agent this entry configures. Valid values: |
| object | Per-agent configuration for this agent. See |
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 |
|---|---|---|
| object | The agent's model source. Set exactly one source. See |
| map | The default model or models the agent launches. See |
| object | Opts the agent into Smart Routing, where supported. Takes a single |
| map | Headers attached to every gateway request from this agent, as key-value string pairs. |
| object | Per-agent client-side tracing. Takes a single |
| object | The agent's own settings, which |
models
models can contain one of the following. For examples, see Choose model sources for each agent.
Field | Type | Description |
|---|---|---|
| array of strings | Static list of full Unity Catalog model service names to make available. |
| string | Full Unity Catalog name of a model provider service. All of its models become available. |
| string | A catalog and schema ( |
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 |
|---|---|---|
| All agents | Overall default model to launch. |
| Claude Code only | Default for the Opus family. |
| Claude Code only | Default for the Sonnet family. |
| Claude Code only | Default for the Haiku family. |
| 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 |
|
|
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 |
|---|---|---|
| array of strings | Exact Unity Catalog resource names. |
| string | A catalog and schema ( |
skills
skills can contain one of the following:
Field | Type | Description |
|---|---|---|
| array of strings | Exact Unity Catalog resource names. |
| string | A catalog and schema ( |
smart_defaults
Field | Type | Description |
|---|---|---|
| string (UUID) | The budget's |
| 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 |
|---|---|---|
| number | Fraction of the budget (0–1) at which this tier activates. For example, |
| string (enum) | Agent to switch the default to. Must appear in |
| 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.