Create an agent
Creates a new agent in the caller’s workspace from the supplied slug, display name, and optional description, instructions, personality settings, aliases, runtime profile, model, avatar URL, and initial enabled skill/MCP subsets, returning the created agent. The slug and aliases must be lowercase 2-32 character handles (letters, digits, hyphens), must not use reserved words, and must not collide with another agent in the workspace; if no avatar URL is given one is generated automatically. Admin only.
Authorizations
Personal Access Token. Send as Authorization: Bearer hq_pat_....
Body
The editable behavior fields. All optional on PATCH (a full-form replace); on create, missing values fall back to the DB column defaults.
Replaces the allowlist set wholesale when present.
Response
The created agent
Free-form short phrases the agent should avoid talking about. Composed as "Be careful around: X, Y, Z" in the system prompt. Empty = no caution block.
True iff instructions is still the platform-seeded value
(admin hasn't customised or tailored yet). The admin UI uses
this to surface a "your agent is still on the default - click
Tailor" banner. Any PATCH that writes instructions flips
this false; the seed migrations set it true on creation.
BCP-47 language codes. The first is the default; subsequent entries are explicit fallbacks. Empty = no language pin (LLM follows the user's language).
Absolute URL of the avatar shown next to this agent's messages. NULL = use the Slack app's default icon for now (fine for legacy single-agent tenants).
Admin-editable system-prompt for this agent. NULL = use the
platform baseline only (the legacy generalist behaviour).
Plumbed through to router_client::compose_system_prompt
which sandwiches it between the Slack-formatting baseline
and the identity-pin footer.
Selected model slug (e.g. claude-opus-4-8). NULL = the runtime's
platform default. Must belong to runtime_profile (billing C).
One of formal | friendly | direct | casual (or NULL = unset
→ no tone pin in the system prompt). Orthogonal to role;
admin choice, not inferrable from "you're a CFO".
One of concise | balanced | detailed (or NULL = unset).
Drives a canonical "Default to brief / balanced / detailed
responses" sentence in the system prompt.