Creating Teammates
Agent id rules, template sources, default models, and saving a Teammate as a reusable org template.
The id
Every Teammate — agent in the API and MCP tools — gets an id when you create it: a lowercase slug of letters, digits, and hyphens, up to 63 characters. The id is immutable — choose it carefully, because you can't rename it later.
The first Teammate on any agent server must be named main. Every server needs at least one baseline Teammate before it can do anything, so the platform enforces this on the first one — it's a rule that applies through the dashboard, API, and MCP alike. Every id after that just needs to be unique on that server.
Where a Teammate's starting config comes from
When you create a Teammate, you pick one of three sources:
| Source | What you get |
|---|---|
| Teammates catalog | A role template we maintain (ops, sales, marketing, SEO, engineering, support, and more) — pre-built workspace files and a starting skill set, auto-updated on future deploys as long as you don't customize it |
| Your org's saved templates | A template your own org previously saved from a customized Teammate — see below |
| Custom | Start from scratch with your own workspace files, no template attached |
Whichever you pick, the template supplies a set of template-specific fields the dashboard prompts you for — for a catalog template, that typically includes at least the Teammate's display name, which seeds its identity document.
Default model
Every Teammate needs a default model, chosen from whatever's on the allowed list for its agent server (see Model configuration). Every new conversation starts on this model; you can switch a single conversation on the fly with the /model command without changing the default itself. The dashboard pre-picks the strongest available option for you — you can change the default before saving, and again at any time afterward.
You can't delete the last Teammate on a server
An agent server always needs at least one Teammate. If you want to remove your only remaining Teammate, delete the agent server instead (see Agent servers) — you can't leave a server with zero Teammates on it.
Managed vs. custom
A Teammate created from a catalog template is managed: it keeps receiving updates to its workspace files automatically on future deploys. The moment you edit a managed Teammate's workspace files directly, it converts to custom — permanently. This conversion cannot be undone; template switching is only available while a Teammate is still managed, so once you've customized one, changing to a different template is no longer an option for that Teammate. See Workspace & soul documents for the full detail on managed-vs-custom and what "customizing" means in practice.
Warning: Customizing a Teammate is one-way. If you think you might want to switch templates later, decide that before you make your first workspace edit — there's no path back to managed once you've customized.
Saving a Teammate as a reusable org template
Once you've customized a Teammate the way you want it, you can save it as a template your whole org can reuse when creating future Teammates. A few rules apply:
- The Teammate needs actual customizations on top of its starting point — saving a template from an untouched, still-managed Teammate is rejected as a no-op.
- The template's slug must be unique within your org.
- A template can't be deleted while any Teammate is still using it.
Saving a Teammate as a template also captures its currently enabled skills, so new Teammates created from it start with the same skill set. This workflow is dashboard-only — there's no API or MCP equivalent for authoring org templates today.
API and MCP
Creating, listing, fetching, and deleting Teammates has full dashboard/API/MCP parity. See API & MCP for the resource map — the one exception is template authoring, described above.