Create a sub-agent under a department

Sub-agents are specialised personas that sit one level below a department. Examples that ship in the seed catalogue: sdr and ae under sales; fpa and bookkeeping under finance; brand and content under marketing. This recipe walks through adding a custom one.

1. Pick a parent department

Sub-agents must belong to one of the 10 seeded departments. List the available parents:

GET /api/agents

200 OK
{ "items": [
    { "slug": "sales", "kind": "department" },
    { "slug": "marketing", "kind": "department" },
    ...
  ]
}

2. Create the sub-agent

Hit POST /api/agents with the parent slug and a new slug for the sub-agent:

POST /api/agents
{
  "slug": "enterprise-sdr",
  "name": "Enterprise SDR",
  "kind": "sub",
  "parentSlug": "sales",
  "systemPrompt": "You are an enterprise sales development rep ...",
  "modelProvider": "anthropic",
  "modelName": "claude-sonnet-4-5"
}

200 OK
{ "slug": "enterprise-sdr",
  "name": "Enterprise SDR",
  "kind": "sub",
  "parentSlug": "sales",
  ... }

3. Inherited defaults

By default a sub-agent inherits from its parent:

  • MCP allowlist — every MCP server enabled for sales is available to enterprise-sdr.
  • Approval policy defaults — if sales requires single-approval for zapier:gmail_send, so does enterprise-sdr unless overridden.
  • KB visibility — KB files attached to sales are visible to enterprise-sdr via the search ranker.
  • Routing — the parent department can delegate to the sub-agent via the in-process router (T17 sub-agent routing in managed-agent.ts).

4. Override an inherited default

Want the enterprise SDR to use a more expensive model than the rest of sales? Patch the agent:

PATCH /api/agents/enterprise-sdr
{ "modelName": "claude-opus-4-7" }

Restrict its MCP allowlist to a subset of the parent's?

PUT /api/agents/enterprise-sdr/mcp-servers/<serverId>
{ "allowed": false }

5. Make it reachable from chat

Sub-agents are reachable in two ways:

  • Direct chat — via POST /api/agents/enterprise-sdr/chat from any authenticated User.
  • Parent delegation — a message to sales can be routed to enterprise-sdr based on system-prompt rules. The orchestrator agent (department orchestrator) typically owns this routing for cross-department questions.

6. Audit

Every action on the new agent writes to the per-Tenant audit chain. agent.created fires once on creation; agent.chat, agent.tool_use, and agent.tool_result fire per interaction. See Audit API.

Background: ADR-006 — Team presets describes the seed catalogue this recipe extends.