Skip to main content
A template is one document in the style of a Kubernetes resource: 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.
The answer is the latest version when the document is identical to it, otherwise the name’s next version with its digest. Because nothing is stored, that version number may be taken by someone else before you create it. A validation error names each field it found wrong in 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.
The console’s template editor shows a document as a form and as YAML side by side, checked by a dry run as you type; see Console.