Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat: fix template creation bogs [LET-7165] (#9015)
Shubham Naik6d453ea58671
diff --git a/fern/pages/cloud/templates.mdx b/fern/pages/cloud/templates.mdxnew file mode 100644index 000000000..179342765--- /dev/null+++ b/fern/pages/cloud/templates.mdx@@ -0,0 +1,131 @@+---+title: Introduction to Agent Templates+slug: guides/templates/overview+---++<Tip>+Agent Templates are a feature in [Letta Cloud](/guides/cloud) that allow you to quickly spawn new agents from a common agent design.+</Tip>++Agent templates allow you to create a common starting point (or *template*) for your agents.+You can define the structure of your agent (its tools and memory) in a template,+then easily create new agents off of that template.++<Frame>+```mermaid+flowchart TD+ subgraph Template["Agent Template v1.0"]+ tools["Custom Tools+ --------+ tool_1+ tool_2+ tool_3"]+ memory["Memory Structure+ ---------------+ system_instructions+ core_memory+ archival_memory"]+ end++ Template --> |Deploy| agent1["Agent 1+ --------+ Custom state"]+ Template --> |Deploy| agent2["Agent 2+ --------+ Custom state"]+ Template --> |Deploy| agent3["Agent 3+ --------+ Custom state"]++ class Template template+ class agent1,agent2,agent3 agent+```+</Frame>++Agent templates support [versioning](/guides/templates/versioning), which allows you to programatically+upgrade all agents on an old version of a template to the new version of the same template.++Agent templates also support [memory variables](/guides/templates/variables), a way to conveniently customize+sections of memory at time of agent creation (when the template is used to create a new agent).++## Agents vs Agent Templates++**Templates** define a common starting point for your **agents**, but they are not agents themselves.+When you are editing a template in the ADE, the ADE will simulate an agent for you+(to help you debug and design your template), but the simulated agent in the simulator is not retained.++You can refresh the simulator and create a new simulated agent from your template at any time by clicking the "Flush Simulation" button 🔄 (at the top of the chat window).++To create a persistent agent from an existing template, you can use the [create agents from template endpoint](/api-reference/templates/agents/create):+```sh+curl -X POST https://app.letta.com/v1/templates/{template_name}:{template_version} \+ -H 'Content-Type: application/json' \+ -H 'Authorization: Bearer YOUR_API_KEY' \+ -d '{}'+```++### Creating a template from an agent+You may have started with an agent and later decide that you'd like to convert it into a template to allow you to easily create new copies of your agent.++To convert an agent (deployed on Letta Cloud) into a template, simply open the agent in the ADE and click the "Convert to Template" button.++## Example usecase: customer service+Imagine you're creating a customer service chatbot application.+You may want every user that starts a chat sesion to get their own personalized agent:+the agent should know things specific to each user, like their purchase history, membership status, and so on.++<Frame>+```mermaid+flowchart TD+ subgraph Template["Customer Service Template"]+ tools["Custom Tools+ --------+ update_ticket_status+ search_knowledge_base+ escalate_ticket"]+ memory["Memory Structure+ ---------------+ name: {{name}}+ ticket: {{ticket}}+ spent: {{amount}}"]+ end++ Template --> |Deploy| user1["Alice's Agent+ --------+ name: Alice+ ticket: T123+ spent: $500"]+ Template --> |Deploy| user2["Bob's Agent+ --------+ name: Bob+ ticket: T124+ spent: $750"]+ Template --> |Deploy| user3["Carol's Agent+ --------+ name: Carol+ ticket: T125+ spent: $1000"]++ class Template template+ class user1,user2,user3 agent+```+</Frame>++However, despite being custom to individual users, each agent may share a common structure:+all agents may have access to the same tools, and the general strucutre of their memory may look the same.+For example, all customer service agents may have the `update_ticket_status` tool that allows the agent to update the status of a support ticket in your backend service.+Additionally, the agents may share a common structure to their memory block storing user information.++This is the perfect scenario to use an **agent template**!++You can take advantage of memory variables to write our user memory (one of our core memory blocks) to exploit the common structure across all users:+```handlebars+The user is contacting me to resolve a customer support issue.+Their name is {{name}} and the ticket number for this request is {{ticket}}.+They have spent ${{amount}} on the platform.+If they have spent over $700, they are a gold customer.+Gold customers get free returns and priority shipping.+```++Notice how the memory block uses variables (wrapped in `{{ }}`) to specify what part of the memory should be defined at agent creation time, vs within the template itself.+When we create an agent using this template, we can specify the values to use in place of the variables.diff --git a/fern/pages/cloud/variables.mdx b/fern/pages/cloud/variables.mdxnew file mode 100644index 000000000..6d5f5c597--- /dev/null+++ b/fern/pages/cloud/variables.mdx@@ -0,0 +1,54 @@+---+title: Memory Variables+slug: guides/templates/variables+---++<Note>+Memory variables are a feature in [agent templates](/guides/cloud/templates) (part of [Letta Cloud](/guides/cloud)).+To use memory variables, you must be using an agent template, not an agent.+</Note>++Memory variables allow you to dynamically define parts of your agent memory at the time of agent creation (when a [template](/guides/cloud/templates) is used to create a new agent).++## Defining variables in memory blocks++To use memory variables in your agent templates, you can define variables in your memory blocks by wrapping them in `{{ }}`.+For example, if you have an agent template called `customer-service-template` designed to handle customer support issues, you might have a block of memory that stores information about the user:+```handlebars+The user is contacting me to resolve a customer support issue.+Their name is {{name}} and the ticket number for this request is {{ticket}}.+```++Once variables have been defined inside of your memory block, they will dynamically appear at variables in the **ADE variables window** (click the "\{\} Variables" button at the top of the chat window to expand the dropdown).++## Simulating variable values in the ADE++<Tip>+Reset the state of the simulated agent by clicking the "Flush Simulation" 🔄 button.+</Tip>++While designing agent templates in the ADE, you can interact with a simulated agent.+The ADE variables window allows you to specify the values of the variables for the simulated agent.++You can see the current state of the simulated agent's memory by clicking the "Simulated" tab in the "Core Memory" panel in the ADE.+If you're using memory variables and do not specify values for the variables in the ADE variables window, the simulated agent will use empty values.++In this prior example, the `name` and `ticket` variables are memory variables that we will specify when we create a new agent - information that we expect to have available at that time.+While designing the agent template, we will likely want to experiment with different values for these variables to make sure that the agent is behaving as expected.+For example, if we change the name of the user from "Alice" to "Bob", the simulated agent should respond accordingly.++## Defining variables during agent creation++When we're ready to create an agent from our template, we can specify the values for the variables using the `variables` parameter in the [create agents from template endpoint](/api-reference/templates/agents/create):+```sh+curl -X POST https://app.letta.com/v1/templates/{template_name}:{template_version} \+ -H 'Content-Type: application/json' \+ -H 'Authorization: Bearer YOUR_API_KEY' \+ -d '{+ "from_template": customer-service-template:latest",+ "variables": {+ "name": "Bob",+ "ticket": "TX-123"+ }+ }'+```diff --git a/fern/pages/cloud/versions.mdx b/fern/pages/cloud/versions.mdxnew file mode 100644index 000000000..905e64c60--- /dev/null+++ b/fern/pages/cloud/versions.mdx@@ -0,0 +1,41 @@+---+title: Versioning Agent Templates+slug: guides/templates/versioning+---++<Note>+Versioning is a feature in [agent templates](/guides/cloud/templates) (part of [Letta Cloud](/guides/cloud/overview)).+To use versioning, you must be using an agent template, not an agent.+</Note>++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](https://docs.docker.com/get-started/docker-concepts/building-images/build-tag-and-publish-an-image/#tagging-images), 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 you can use the [create agents from template endpoint](/api-reference/templates/agents/create)+For example, to deploy an agent from a template called `template-name` at version 2, you would use `:2` as the template tag:+```sh+curl -X POST https://app.letta.com/v1/templates/{template_name}:2 \+ -H 'Content-Type: application/json' \+ -H 'Authorization: Bearer YOUR_API_KEY' \+ -d '{}'+```