Loading

Roles: Which Model Each Feature Uses

Every AI feature on the platform asks for a role rather than a particular model. The roles table on AI Settings decides which provider and model each role uses, and any limits on it, so you can put a strong model where quality matters and a cheaper one where it does not, without touching the features themselves.

Where to find it

Architect Panel → Configuration:

  • AI Settings — the section Which provider each AI feature uses

Architect Panel → Activity:

  • AI Usage — Test a role, and usage grouped by feature

The platform's roles

  • builder: the default. Every role that names no provider of its own uses this one.
  • onboarding: the sign-up wizard, which turns a description of a business into an app blueprint. It runs for anonymous visitors.
  • aibuilder: the AI Builder, which turns a request into a change set for the app.
  • ide: App Code, which writes extension source. A stronger model here means fewer repair rounds.
  • biquery: the Report Builder's assistant (the screen calls it the Query Builder assistant). It is sent field names and labels, never a record value.
  • ocr: AI reading of scanned images for the document index. The image leaves the installation.
  • erpfeed: coding suggestions on the ERP Feed Queue, one request per uncoded row, only when a user asks.
  • a2a: the planner behind Agent Access (A2A).

Image and video generation use two further roles, image and video, whose models are set in the AI images and video section instead. TypeSafe Jev is not a role at all: it has its own section.

How a role finds its model

  • Provider and model both set: that pair is used.
  • Provider set, model blank: the provider's Default model from its own section.
  • Provider blank (Inherit): the builder provider and the builder model. The model always travels with its provider, so a role can never be handed one provider's model id on another.

Under each role's name, a Uses: line shows what it resolves to right now, so you can see the effect of inheritance without working it out.

The other columns

  • Effort: how hard a reasoning model thinks (low to max; none on OpenAI models only). A blank effort inherits the builder's only while the role also runs the builder's model, because some models refuse an effort setting.
  • Max tokens: the most the model may write in one answer.
  • Timeout (s): seconds allowed per attempt.
  • Retries: how many times a failed connection is retried; 0 means one try.
  • Schema mode: how a structured answer is asked for. Leave it at Default unless support advises otherwise.
  • Fallback model: a second model on the same provider, tried when the first refuses to answer.

Blank means inherit. The sign-up wizard, AI Builder, App Code and Report Builder assistant run while a person waits, so they keep their own limit of about 100 seconds per call with no retry; a role's Timeout can shorten that but never lengthen it. Feed Queue suggestions are held to 60 seconds a call the same way.

Changing a feature's model

  1. Open AI Settings and find the role's row.
  2. Choose a Provider whose credentials are Set, and enter a Model id, or leave it blank to take that provider's default.
  3. Press the section's Save, and check the Uses: line now shows what you intended.
  4. On AI Usage, press Test beside the role.

Adding a role for a client app

A custom feature on your installation asks for a role by name, chosen by whoever wrote it. To give that role a provider, fill in Add a role under the table: the role name, a provider (or Inherit from builder), and optionally a model, then Save. A name is 2 to 40 lower-case letters, digits and underscores, starting with a letter, and cannot be a provider's name. A role you added can later be ticked Remove; the platform's own roles cannot. A role the file has never named simply behaves like builder.

What goes wrong, and how to tell

  • A role is missing from Test a role on AI Usage: that list shows builder and every role the file names a provider entry for. Set the role's provider on AI Settings and it appears.
  • Every call on a role fails straight after you set Effort: the model does not take an effort setting. Set Effort back to Default.
  • A role changed model when you only changed builder: it was inheriting. Give it a provider of its own to pin it.
  • "There is already a role called..." when adding: pick another name, or edit the existing row.

Worked example

An organisation runs everything on one Claude model. Developers say App Code needs several repair rounds per extension, so the architect sets the ide row to the same provider with a stronger model. Scanned post is read by the ocr role, which is moved to a smaller, cheaper model that can still read images, and its Max tokens left blank. Both rows are tested on AI Usage, and a month later the usage table grouped by feature shows the saving on ocr paid for the extra cost on ide.

Recommendations

  • Set builder first and let everything inherit until there is a reason not to.
  • Pin a role explicitly once its quality or cost matters, so a later change to builder does not move it.
  • Change provider and model together, and read the Uses: line before saving.
  • Leave Schema mode at Default unless advised otherwise.
  • Test each role after a change, and compare its cost on AI Usage a few weeks later.