Reference
Template schema
Field constraints, rejected shapes and the 7 `TEAM_TEMPLATE_*` codes of `agentkit.studio.team-template/v1`.
The team template contract is agentkit.studio.team-template/v1. It is the normalization boundary between a catalog row and a TeamDefinition.
| Constant | Value | Meaning |
|---|
TEAM_TEMPLATE_CONTRACT | agentkit.studio.team-template/v1 | Contract version |
TEAM_TEMPLATE_RUNTIMES | dsh-native · harness | Runtimes a role may use |
TEAM_PLACEHOLDER_MODELS | one-team-model | Placeholder models rejected by validation |
TEAM_DEFAULT_MODEL | [内部模型代号,见源码] | Internal model code name, redacted here |
validateTeamTemplate() is the only entry point. The limits below are extracted from the requiredText / optionalText calls in the validator, so they share one source.
| Field | Limit | Unit |
|---|
instructions | 16000 | chars |
roles[].instructions | 8000 | chars |
roles[].template.id | 256 | chars |
roles[].template.digest | 256 | chars |
roles[].model / defaultModel | 256 | chars |
id | 128 | chars |
name | 120 | chars |
roles[].label | 80 | chars |
roles[].template.version | 64 | chars |
roles[].name | 64 | chars |
Additional format constraints:
| Field | Type / pattern | Constraint |
|---|
kind | "team" | Fixed value; anything else is rejected |
id | ^[a-z][a-z0-9-]*$ | Lowercase letter first, then lowercase letters, digits and hyphens |
version | ^\d+\.\d+\.\d+$ | Strict three-part semver |
roles | array | 2–9 roles; roles[0].name must be lead |
roles[].name | ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ | Hyphen-separated and unique across roles |
roles[].template.version | semver | Falls back to the team version |
| Input | Rule | Fix |
|---|
roles[].agentId | A role cannot reference a plain Agent | Use an immutable template reference |
roles[].source.kind | Rejected when the value is agent | Same as above |
subAgents / sub_agents | A role cannot declare a nested subagent | Compose roles at the team level |
roles[].template | Missing id or digest | Add the content lock |
| Placeholder model | one-team-model | Must be replaced with a real model profile |
runtime.type | dsh-native · harness | Only these runtimes are accepted |
| Code | Location | Meaning |
|---|
TEAM_TEMPLATE_INVALID | src/team-template-contract.mjs:21 | Team roles and templates. |
TEAM_TEMPLATE_MODEL_INVALID | src/team-template-contract.mjs:32 | Team roles and templates. |
TEAM_TEMPLATE_ROLE_SOURCE_INVALID | src/team-template-contract.mjs:38 | Team roles and templates. |
TEAM_TEMPLATE_ROLE_INVALID | src/team-template-contract.mjs:58 | Team roles and templates. |
TEAM_TEMPLATE_ROLE_SPEC_INVALID | src/team-template-contract.mjs:92 | Team roles and templates. |
TEAM_TEMPLATE_RUNTIME_UNSUPPORTED | src/team-template-contract.mjs:94 | Team roles and templates. |
TEAM_TEMPLATE_NESTED_TEAM_UNSUPPORTED | src/team-template-contract.mjs:95 | Team roles and templates. |
| Item | Value | Notes |
|---|
| Contract | agentkit.studio.team-template/v1 | A new required field is a breaking change |
| Role count | 2–9 | Upper bound of one team |
| Runtimes | dsh-native · harness | codex cannot be a team role runtime |
| Error codes | 7 | All start with TEAM_TEMPLATE_ or TEAM_ |
| Item | Source |
|---|
| Template contract and validation | src/team-template-contract.mjs |
| Template catalog | src/template-catalog-source.mjs |
| Team runtime | src/studio-team-runtime.mjs |
| Template summon | src/team-template-summon.mjs |
Related tests:
| Test file | Location |
|---|
| team-template-contract.test.mjs | tests/team-template-contract.test.mjs |
| team-template-summon.test.mjs | tests/team-template-summon.test.mjs |