Skip to main content
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.
Belongs to a workspace · Selects ≤ 8 roles, ≤ 8 model selectors, ≤ 16 hooks · Used by many agents (1:N) · Versioned on every edit

​
Rules

  • Editing a profile changes every agent attached to it. See Rules.
  • Omitting hooks installs the default approvals; 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.
  • GET/POST /v1/profiles, PATCH/DELETE /v1/profiles/{profileId}.
  • A PATCH to configuration.roleIds replaces the list; it does not merge.