The handbook
Manage usersManage rolesMint and revoke API keysManage tenantsRun agents and chatIngest and curate contextManage cultivatorsPer-tenant agent overridesReview the audit log
Workflows

Workflows: Per-tenant agent overrides

Overrides let you customise a code-declared agent for one tenant without touching code. They are the v1 substitute for DB-defined agents.

Prerequisites

  • acaso_os:admin on the connection. The Overrides tab is hidden for non-admins.

Open the overrides editor

Open /agents/{name} and click the Overrides tab. The page calls GET /v1/admin/tenants/{slug}/agents/{name}/overrides using the active connection's tenant slug and renders the current override values, or an empty form if none exist.

Typed editor vs raw JSON

The editor's shape depends on whether the agent declares an overrides_schema.

  • Schema present. Fields render as typed inputs per the schema (string, integer, enum dropdowns) with inline validation. Submit is disabled until the form is valid.
  • No schema. A raw JSON textarea is shown with client-side JSON syntax validation. The backend also validates and returns 400 on schema mismatch.

Common overridable fields (when the agent exposes them):

FieldEffect
modelSwap the LLM (claude-opus-4-7 → claude-haiku-4-5).
tools.disabledHide specific tools from the agent for this tenant.
Tool argument defaultsPre-seed values the LLM may otherwise leave blank.

The system prompt is no longer an override. Prompt text now lives in versioned, per-tenant Prompts (ADR-0006) edited on the System prompt page (/agents/{name}/prompt) — immutable versions, a movable production label, history, and diff. The old system_prompt / system_prompt_append override keys are rejected.

Save the overrides

Click Save. The console calls PUT /v1/admin/tenants/{slug}/agents/{name}/overrides with the form payload. A success toast confirms the save and the audit log records action = agent.overrides.update.

The next run of the agent in this tenant picks up the override. Runs in other tenants are unaffected.

Reset to defaults

Click Reset to defaults and confirm. The console calls DELETE /v1/admin/tenants/{slug}/agents/{name}/overrides. The form re-renders empty and the agent reverts to its code-declared defaults on the next run.

Test the override

The simplest verification:

  1. Open a chat with the agent.
  2. Send a probe message that surfaces the overridden field (for example "What model are you?" if you overrode model).
  3. Confirm the response matches the override.

For deeper verification, inspect the audit log for the next agent.run entry; the metadata includes the resolved configuration.

When not to use overrides

Overrides are tenant-scoped configuration, not code. Pick the right surface based on the change:

  • Applies to every tenant. Change the code instead.
  • Depends on per-request inputs. Add a tool.
  • Stable per-tenant delta. Overrides are the right surface.
PreviousWorkflowsManage cultivatorsNext WorkflowsReview the audit log