apiVersion, kind, metadata, and spec. It holds everything an agent starts from and names no version; the server assigns one.
The document
agents/code-maintainer/template.yaml
Capabilities are described in Capabilities, and what each setting does to a running session in Configuration.
YAML and JSON spelling
The same document can be written in YAML or JSON. YAML spells fields in snake_case (system_prompt, small_model); JSON, and the TypeScript and Go types, spell them in camelCase (systemPrompt, smallModel). apiVersion and kind keep their spelling everywhere. The SDKs send a file path’s YAML as it is and a document object as JSON. Both spellings of the same content get the same digest, so they are the same version.
Create a version
Agents reference one exact version. A new version gives new agents; existing agents keep the version they were created from and change their own configuration instead.
Check a document with a dry run
A dry run runs every check of a create and returns the version the create would return, without storing anything. Use it in CI, or while editing.details, for example spec.mcp[github].url. See Errors.
Create from a document in code
Pass a document instead of a path; it is sent as JSON, spelled in camelCase.Read, list, and delete
get("name@version")returns that version with its document;get("name")returns the latest.list()returns the latest version of each template, newest first;list({ name })returns every version of one name.- Deleting a version is
409 conflict(template_in_use) while any agent references it. Version numbers are never reused.
Save an agent as a template
An agent you tuned through its own capabilities can be saved as a template.agent.export() returns the agent’s effective configuration as a template document; creating a template from it saves it, under the template’s name as its next version or under a new name as version 1. The agent itself is unchanged.