Organization Agent settings

Organization-scoped Agent defaults

Runtime model is currently the first and only Organization Agent Setting. It supplies defaults used by Agents unless they have an explicit override.

Open the Organization-wide administrative surface at:

/dashboard/{org_id}/settings?tab=agents

It contains the default model and source, inheriting and override counts, allowed models, and an expandable Agent model map.

Resolve defaults and Agent overrides

effective_default_model(organization)
  = organization-owned default
  or platform default

effective_model(agent)
  = Agent-specific override
  or effective_default_model(organization)

1. An Organization either owns a default or follows the installation platform default.
2. Each Agent either inherits the Organization’s effective default or uses a specific override.

There is at most one Agent Settings row per Organization, created lazily on the first write. No settings row and a row with default_model = null are equivalent: both follow the platform default. An Organization that never customizes this surface tracks the installation’s current default; the creation-time value is not a permanent snapshot.

Choose a default source

Selecting a concrete model creates or updates the Organization-owned setting. Clearing it with null resumes following the platform default. Omitting default_model from an update leaves the existing choice unchanged.

The read model includes default_model, effective_default_model, default_model_source, inheriting_agent_count, override_agent_count, and updated_at. The counts cover non-deleted Agents; updated_at is present after a persisted settings change.

Keep allowed models separate from the default

Allowed models
├── model-a
├── model-b
└── model-c

Organization default
└── model-b

Agent A → inherits model-b
Agent B → overrides with model-c

Adding a model to the allowlist does not make it the default, and changing the default does not remove other allowed models.

Preserve explicit consumers

An Organization-owned default must be in allowed_models. Selecting a default outside the list is rejected, and removing the selected default is rejected until it is changed or cleared. Explicit Agent overrides must also remain allowed; removing a pinned model is refused and identifies affected Agents. No Agent is silently repinned by an allowlist edit.

1. Change the Organization default to another allowed model, or clear it.
2. Update or clear every Agent override using the model.
3. Save the revised allowlist.

Validate patterns with the model catalogue

The allowlist supports exact model identifiers and supported glob patterns. An Organization-owned default must be one concrete catalogue model, not a glob.

New entries are checked against the current OpenRouter catalogue when available. If the catalogue is temporarily unavailable, the failure is logged, existing settings remain intact, and validation may be skipped so administrators are not locked out. Models that later disappear from the catalogue can remain as orphaned entries until removed.

When choosing a default, Agent Barn confirms the model is allowlisted and concrete, checks the live catalogue when available, saves the setting, then reports the resolved value and impact counts. When changing the allowlist, it preserves the owned default and explicit overrides, validates new entries where possible, retains intentional orphans, and rejects changes that would strand an explicit consumer.

Choose inheritance or a custom model

An Agent model control offers two explicit choices: default (Use organization default) or custom (Choose a specific model).

Using the default stores the inheritance sentinel rather than copying the current model. Choosing a specific model creates an explicit override. Two Agents showing the same model can therefore have different sources: an inheriting Agent moves when the default changes, while a custom Agent remains pinned.

Changing an individual override requires permission to update that Agent. Agent Owner or Editor access alone does not grant the Organization-wide authority to change defaults or the allowlist.

Understand effective, running, and pending models

The Runtime reads its model at startup and does not continuously reload Organization settings. When a running inheriting Agent’s default changes, its effective model changes while its running model remains the previous value; pending_model shows what will apply after restart.

Agent A running model: model-a
Organization effective default: model-b
Agent A pending model: model-b

Agent A continues using model-a until restarted. A default change does not hot-reload an active Agent or restart any Agent automatically.

Review policy blast radius

A default-change confirmation should show how many Agents follow the default, which model they will use after restart, and how many explicit overrides remain unaffected. The model map lists each accessible Agent’s name, displayed model, default or custom source, and a pending-switch note when restart would change the model.

Summary counts include all non-deleted Agents in the Organization, even when the caller cannot see every Agent by name. They describe policy blast radius and do not bypass Agent Access.

Organization default: null
Platform default: model-a
Agent A: inherits
Agent A effective model: model-a

Allowed models: model-a, model-b
Organization default: model-b
Agent A: inherits
Agent B: override model-a

Permissions and audit behavior

Reading and writing Agent Settings requires organization.update. Organization Owners and Admins can manage it; Members cannot.

Organization Permission → Organization default and allowlist
Agent Access Permission → Individual Agent override

Meaningful default changes emit organization.agent_settings.changed. Allowed-model changes emit organization.model_allowlist.changed. Both use the Domain Event and security-audit path; an unchanged save emits no extra event. They are not Communications journal entries.

API reference

GET /api/v1/organizations/{organization_id}/agent-settings
PUT /api/v1/organizations/{organization_id}/agent-settings

{
  "default_model": null,
  "effective_default_model": "<platform-model>",
  "default_model_source": "platform",
  "inheriting_agent_count": 3,
  "override_agent_count": 1,
  "updated_at": null
}

Select an Organization-owned default:

{
  "default_model": "<allowed-model>"
}

Resume following the platform:

{
  "default_model": null
}

Allowed models use the Organization update route, not the Agent Settings request:

PATCH /api/v1/organizations/{organization_id}

{
  "allowed_models": [
    "<model-or-pattern>"
  ]
}

Related guides

• Create an Organization
• Manage Organizations and members
• Roles, Permissions, and Agent Access
• Configure an Agent and manage the Agent lifecycle
• Work with Domain Events and Delivery