> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiles

> Behavior you define once and share.

A profile is the complete definition of how an agent behaves, and it holds
exactly four things: `models` (which models it may use, first one is the
default), `systemPrompt` (the instructions it always carries), `hooks` (its
approvals and guardrails), and `roleIds` (where its tools come from).

Think of it like a base image. Many agents can point at one profile, and they
all get identical tool access, because there is no per-agent override. If one
agent needs something the others shouldn't have, give it its own profile.

Every edit bumps the profile's version. A turn uses whichever version is
current when it starts, so attached agents pick up your change on their next
turn, and anything already running keeps the snapshot it began with. This cuts
both ways: setting `roleIds: []` strips the tools from every agent on that
profile at once.

You don't have to create one up front. `POST /v1/agents` accepts an inline
`profile` with the same four fields and creates a profile just for that agent.
Create them separately when several agents should share one.

<Info>
  **Belongs to** a workspace · **Selects** ≤ 8 roles, ≤ 8 model selectors, ≤ 16
  hooks · **Used by** many agents (1:N) · **Versioned** on every edit
</Info>

## Rules

* Editing a profile changes every agent attached to it. See
  [Rules](/model/rules).
* Omitting `hooks` installs the [default approvals](/model/hooks); `hooks: []`
  installs none.
* Omitting `roleIds` creates a profile with no tool access. The one exception
  is an agent creating an agent inline: there, omitting it inherits the
  caller's roles, and `roleIds: []` is how you get a tool-less child.

## API

* Selector grammar and the catalog: [Models](/reference/models).
* `GET`/`POST /v1/profiles`, `PATCH`/`DELETE /v1/profiles/{profileId}`.
* A `PATCH` to `configuration.roleIds` replaces the list; it does not merge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.