AgentKit Studio
Ecosystem and plugins

Expert templates

Define expert teams with agentkit.studio.team-template/v1 — field tables, role blueprint constraints, validation error codes, publishing and summon flows.

An expert template is JSON, not code. A team template describes who composes the team, what instructions each role carries, and which resources it may bind. Studio validates it, then hands it to DSH Agent Teams to run.

ConceptWhat it isContract
Expert templateA configuration snapshot of one preset agentFollows Agent Revision semantics, see core concepts
Team templateA multi-role collaboration unitagentkit.studio.team-template/v1 (this page)

This page covers team templates only — they are the one template type with its own schema contract.

Top-level fields

FieldTypeRequiredConstraintSource
kindstring✅Must be exactly "team"team-template-contract.mjs:52
idstring✅/^[a-z][a-z0-9-]*$/, ≤128 chars:53-54
versionstring✅Strict \d+\.\d+\.\d+ (no -rc suffix):54
namestring✅≤120 chars:55
instructionsstring✅≤16000 chars, team-level collaboration instructions:56
rolesarray✅2–9 entries, and roles[0].name must be lead:57-58
defaultModel / modelstring—≤256 chars; must not be a placeholder:80
contractstring—Defaults to agentkit.studio.team-template/v1:83
catalogIdstring—Catalog ownership, optional:48

A team starts at two roles

roles.length < 2 fails immediately. With a single role you do not need a team — use an ordinary expert template. Source: team-template-contract.mjs:58.

Role fields

FieldTypeRequiredConstraintSource
namestring✅/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, ≤64 chars, unique within the team:61-62
labelstring—≤80 chars; defaults to name:65
instructionsstring—≤8000 chars:66-67
agentPreset / agentPresetIdstring—≤256 chars:68
model / modelId / modelProfileIdstring—≤256 chars; must not be a placeholder:69
template.idstring✅≤256 chars, points at an immutable template:40
template.versionstring✅semver, ≤64; falls back to the team version:45-47
template.digeststring✅≤256 chars, the content lock:46
template.catalogIdstring—Falls back to the team catalogId:48

Two hard rules for role names

RuleOn violationSource
Only the first role may be named leadTEAM_TEMPLATE_ROLE_INVALID:62
Role names must be uniqueTEAM_TEMPLATE_ROLE_INVALID:62

Roles may not reference plain agents

{
  "name": "writer",
  "agentId": "ar-12345"
}

This fails with TEAM_TEMPLATE_ROLE_INVALID: "role 'writer' must not reference a plain agent; use an immutable template reference instead."

Why? A plain agent is mutable — its Revision advances. A team needs reproducible members, so it may only reference immutable templates carrying a digest. Source: team-template-contract.mjs:63.

Role blueprint (role spec)

The template field points at an agent definition; that definition's spec is validated again by validateTeamRoleSpec:

FieldConstraintOn violation
runtime.typeOnly dsh-native or harnessTEAM_TEMPLATE_RUNTIME_UNSUPPORTED
subAgents / sub_agentsForbiddenTEAM_TEMPLATE_NESTED_TEAM_UNSUPPORTED
instructions.systemMust be a non-empty stringTEAM_TEMPLATE_ROLE_SPEC_INVALID
bindingsMust be an object (not an array)TEAM_TEMPLATE_ROLE_SPEC_INVALID
bindings.modelProfileId / modelProfileIds[]Must not be a placeholderTEAM_TEMPLATE_MODEL_INVALID

Codex is out of scope for teams

TEAM_TEMPLATE_RUNTIMES has exactly two values: dsh-native and harness. Even though the Studio agent form offers codex, team roles cannot use it. Source: team-template-contract.mjs:4,9,94.

Placeholder models

Templates must not keep placeholders, otherwise a summoned team runs against a fake model:

PlaceholderChecked whereError code
one-team-modelTeam defaultModel / modelTEAM_TEMPLATE_MODEL_INVALID
one-team-modelRole model and friendsTEAM_TEMPLATE_MODEL_INVALID
one-team-modelCatalog audit recursively scans any key containing modelTEAM_TEMPLATE_PLACEHOLDER_MODEL

Source: team-template-contract.mjs:16,30-34, team-template-audit.mjs:20-35,56.

Complete example

{
  "kind": "team",
  "id": "release-crew",
  "version": "1.2.0",
  "name": "Release crew",
  "instructions": "lead splits the release checklist; writer produces release notes; reviewer signs off before merge.",
  "defaultModel": "model-profile-prod",
  "roles": [
    { "name": "lead", "label": "Lead", "instructions": "Split work, delegate, and summarise.",
      "template": { "id": "agent/team-lead", "version": "1.0.0", "digest": "sha256:9f2c…" } },
    { "name": "writer", "label": "Writer", "instructions": "Turn changes into release notes.",
      "template": { "id": "agent/tech-writer", "version": "1.0.0", "digest": "sha256:4ab7…" } },
    { "name": "reviewer", "label": "Reviewer", "instructions": "Check facts and links.",
      "template": { "id": "agent/reviewer", "version": "1.0.0", "digest": "sha256:77e1…" } }
  ]
}

Validation error code reference

Error codeTriggerFix
TEAM_TEMPLATE_INVALIDkind !== "team"; id / version / name / instructions empty or too longWalk the top-level field table
TEAM_TEMPLATE_ROLE_INVALIDRole count outside 2–9; lead not first; duplicate or malformed name; role references a plain agentAdjust the roles array
TEAM_TEMPLATE_ROLE_SOURCE_INVALIDtemplate missing, not an object, missing id or digest, or version is not semverFill in template.id / .version / .digest
TEAM_TEMPLATE_MODEL_INVALIDA model field is the placeholderUse a real model profile id
TEAM_TEMPLATE_ROLE_SPEC_INVALIDRole blueprint is not an object; missing instructions.system; bindings is not an objectFix the role definition
TEAM_TEMPLATE_RUNTIME_UNSUPPORTEDruntime.type is neither dsh-native nor harnessChange the runtime
TEAM_TEMPLATE_NESTED_TEAM_UNSUPPORTEDA role declares subAgents / sub_agentsRemove the nested declaration
TEAM_TEMPLATE_PLACEHOLDER_MODELCatalog audit found a leftover placeholderReplace every model field
TEAM_ROLE_DEFINITION_MISSINGRole template definition not found (error when requireRoleDefinitions, else warning)Publish the role template first
TEAM_ROLE_DEFINITION_KIND_INVALIDRole template kind is not agentUse an agent definition
TEAM_ROLE_NOT_TEAM_ONLYRole template is not marked teamRoleOnly: trueAdd the marker
TEAM_TEMPLATE_NONE (warning)The catalog contains no kind=team templateNot an error, informational

Source: team-template-contract.mjs, team-template-audit.mjs:51-74.

Audit

Run a catalog audit before publishing; it never mutates input, only returns a report:

import { auditTeamTemplateCatalog } from './src/team-template-audit.mjs';
const report = auditTeamTemplateCatalog({
  items,                        // Catalog listing items
  definitions,                  // Role template definitions (Map or plain object)
  requireRoleDefinitions: true, // Escalate a missing definition to an error
});
// report: { ok, teamCount, errors[], warnings[] }, each issue { code, message, path? }

Source: team-template-audit.mjs:42-74.

Publishing and summoning

OperationPurpose
team-templates/list / team-templates/detailList and read team templates
templates/summon-plan / templates/summonBuild a summon plan (no persist) and execute the summon
template-workflows/{start,status,cancel,detail,cache,clearCache}Progress, cancellation, and cache for long tasks

Summon states: running → succeeded / failed / cancelled; after a process restart a read returns interrupted. Source: src/template-workflows.mjs:17-35.

How experts and teams run is covered in experts and local teams, the machine-readable field definitions in the template schema reference, and every error code in the error reference.

On this page