How profiles work
Commands in an agent name profiles; 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 five kinds
| Profile | Used by | Holds |
|---|---|---|
| LLM profile | the llm command | Vendor, adapter, URL, headers, the model and its prices, limits |
| Prompt profile | the prompt command | System and user prompt text, stored encrypted, reused across agents |
| API profile | the api command | Base URL, headers, the connection pool |
| Database profile | the db command | Connection string and pool settings |
| MCP server | the mcp field in an llm command | The server's URL and its connection settings. |
Why profiles
A profile is changed once, and every agent that uses the profile picks up the change on its next run. Three things follow from that.
- Moving between environments. The same agents run against development, staging and production by changing the profiles, not the agents. An agent that names
orders_dbdoes not know which database that is. - Retiring a model or a service. When a model is sunset 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.secretreference read at call time; see Secret vault.
Rules that apply to every profile
- A profile name is letters, digits and underscores. A profile name starts with a letter and ends with a letter or a digit. MCP names are an exception - they cannot have underscores.
- Each profile page in the GUI 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 GUI shows the limit on the profile's page.
- A profile carries a documentation 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 a notification. See How configuration works.