Priority belongs to you
The order of providers in config.json is the priority, and /agent inside a session edits it for you. Your order always comes first, and the examples in this documentation are only examples. The same provider may appear more than once, for example two accounts of the same agent.
Installed agents you did not list are not ignored: they follow after the ones you listed, so an agent you install later is found without editing anything. Agents you did not rank are tried in the order of their ids, and none is preferred over another. Your own order always comes first. Set "auto_detect": false to use only what you listed. Whether an agent can start still depends on the permission ceiling, see Configuring agents.
Which entry runs
When you start a session, uuldana-cli walks the list from the top and starts the first entry that:
- is not resting after an earlier usage limit;
- is installed and recognized;
- can run inside the permission ceiling, using flags the provider really enforces;
- for a handoff, accepts an initial prompt.
An entry that does not qualify is skipped, and the reason is kept so that uuldana-cli can tell you what blocked each one. Position alone does not make an entry eligible, and an unknown capability does not count as supported.
When nothing can run
If every entry is resting or refused, uuldana-cli prints one line per entry and, when entries are resting, how many minutes until the first one returns. It exits with code 1.
Resting entries are remembered
Resting entries are saved in the cooldown table in the data directory, so a new uuldana does not walk back into an account that has just run out. See Automatic failover.