How profiles work

Commands in an agent name profiles, and profiles hold the details. An llm command says "profile": "gpt5_mini", and the LLM profile of that name holds the URL, the headers, the model and the prices.

The four kinds

Why profiles

A profile is changed once, and every agent that uses it applies the change on its next run. This has three benefits.

• Moving between environments. The same agents run against development, staging and production by changing the profiles, not the agents. An agent that names orders_db does not know which database that is.
• Retiring a model or a service. When a model is retired or an API moves, one profile changes and every agent follows.
• Keeping credentials out of agents. A profile's headers and connection string are dynamic strings, so a credential is a sys.secret reference read at call time; see Secret vault.

Rules that apply to every profile

• A profile name is letters, digits and underscores. It starts with a letter and ends with a letter or a digit. MCP server names are the exception: no underscores.
• Each profile page in the UI shows which agents use the profile. A profile in use cannot be deleted; remove the reference from the agents first.
• Each kind of profile has a limit on how many an account may hold. The UI shows the limit on the profile's page.
• A profile carries a note. Draft with AI reads the note to learn what the API serves or what the database holds, so a useful note leads to a better draft.
• Profiles are versioned like every configuration part: a save is refused when someone else changed the profile first, and every create, update and delete produces an audit log entry. See Runtime sync.