Versioning Agent Templates

Versions allow you to keep track of the changes you’ve made to your template over time. Agent templates follow the versioning convention of template-name:version-number.

Similar to Docker tags, you can specify the latest version of a template using the latest keyword (template-name:latest).

Creating a new template version

When you create a template, it starts off at version 1. Once you’ve make edits to your template in the ADE, you can create a new version of the template by clicking the “Template” button in the ADE (top right), then clicking “Save new template version”. Version numbers are incremented automatically (e.g. version 1 becomes version 2).

Migrating existing agents to a new template version

If you’ve deployed agents on a previous version of the template, you’ll be asked if you want to migrate your existing agents to the new version of the template. When you migrate existing agents to a new template version, Letta Cloud will re-create your existing agents using the new template information, but keeping prior agent state such as the conversation history, and injecting memory variables as needed.

When should I migrate (or not migrate) my agents?

One reason you might want to migrate your agents is if you’ve added new tools to your agent template: migrating existing agents to the new version of the template will give them access to the new tools, while retaining all of their prior state. Another example usecase is if you make modifications to your prompts to tune your agent behavior - if you find a modification works well, you can save a new version with the prompt edits, and migrate all deployed agents to the new version.

Forking an agent template

If you decide to make significant changes to your agent and would prefer to make a new template to track your changes, you can easily create a new agent template from an existing template by forking your template (click the settings button ⚙️ in the ADE, then click “Fork Template”).

Specifying a version when creating an agent

You can specify a template version when creating an agent in the agent creation endpoint. For example, to deploy an agent from a template called template-name at version 2, you would use :v2 as the template tag:

1
curl -X POST https://api.letta.com/v1/agents \
2
  -H 'Content-Type: application/json' \
3
  -H 'Authorization: Bearer YOUR_API_KEY' \
4
  -d '{
5
    "from_template": template-name:v2"
6
  }'