AgentKit Studio
Reference

Template schema

Field constraints, rejected shapes and the 7 `TEAM_TEMPLATE_*` codes of `agentkit.studio.team-template/v1`.

Contract constants

The team template contract is agentkit.studio.team-template/v1. It is the normalization boundary between a catalog row and a TeamDefinition.

ConstantValueMeaning
TEAM_TEMPLATE_CONTRACTagentkit.studio.team-template/v1Contract version
TEAM_TEMPLATE_RUNTIMESdsh-native · harnessRuntimes a role may use
TEAM_PLACEHOLDER_MODELSone-team-modelPlaceholder models rejected by validation
TEAM_DEFAULT_MODEL[内部模型代号,见源码]Internal model code name, redacted here

Field constraints

validateTeamTemplate() is the only entry point. The limits below are extracted from the requiredText / optionalText calls in the validator, so they share one source.

FieldLimitUnit
instructions16000chars
roles[].instructions8000chars
roles[].template.id256chars
roles[].template.digest256chars
roles[].model / defaultModel256chars
id128chars
name120chars
roles[].label80chars
roles[].template.version64chars
roles[].name64chars

Additional format constraints:

FieldType / patternConstraint
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
rolesarray2–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.versionsemverFalls back to the team version

Rejected shapes

InputRuleFix
roles[].agentIdA role cannot reference a plain AgentUse an immutable template reference
roles[].source.kindRejected when the value is agentSame as above
subAgents / sub_agentsA role cannot declare a nested subagentCompose roles at the team level
roles[].templateMissing id or digestAdd the content lock
Placeholder modelone-team-modelMust be replaced with a real model profile
runtime.typedsh-native · harnessOnly these runtimes are accepted

Error codes

CodeLocationMeaning
TEAM_TEMPLATE_INVALIDsrc/team-template-contract.mjs:21Team roles and templates.
TEAM_TEMPLATE_MODEL_INVALIDsrc/team-template-contract.mjs:32Team roles and templates.
TEAM_TEMPLATE_ROLE_SOURCE_INVALIDsrc/team-template-contract.mjs:38Team roles and templates.
TEAM_TEMPLATE_ROLE_INVALIDsrc/team-template-contract.mjs:58Team roles and templates.
TEAM_TEMPLATE_ROLE_SPEC_INVALIDsrc/team-template-contract.mjs:92Team roles and templates.
TEAM_TEMPLATE_RUNTIME_UNSUPPORTEDsrc/team-template-contract.mjs:94Team roles and templates.
TEAM_TEMPLATE_NESTED_TEAM_UNSUPPORTEDsrc/team-template-contract.mjs:95Team roles and templates.

Version and compatibility

ItemValueNotes
Contractagentkit.studio.team-template/v1A new required field is a breaking change
Role count2–9Upper bound of one team
Runtimesdsh-native · harnesscodex cannot be a team role runtime
Error codes7All start with TEAM_TEMPLATE_ or TEAM_

Developer entry points

ItemSource
Template contract and validationsrc/team-template-contract.mjs
Template catalogsrc/template-catalog-source.mjs
Team runtimesrc/studio-team-runtime.mjs
Template summonsrc/team-template-summon.mjs

Related tests:

Test fileLocation
team-template-contract.test.mjstests/team-template-contract.test.mjs
team-template-summon.test.mjstests/team-template-summon.test.mjs

On this page