diff --git a/fern/pages/cloud/templates.mdx b/fern/pages/cloud/templates.mdx new file mode 100644 index 00000000..17934276 --- /dev/null +++ b/fern/pages/cloud/templates.mdx @@ -0,0 +1,131 @@ +--- +title: Introduction to Agent Templates +slug: guides/templates/overview +--- + + +Agent Templates are a feature in [Letta Cloud](/guides/cloud) that allow you to quickly spawn new agents from a common agent design. + + +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. + + +```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 +``` + + +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. + + +```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 +``` + + +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.mdx new file mode 100644 index 00000000..6d5f5c59 --- /dev/null +++ b/fern/pages/cloud/variables.mdx @@ -0,0 +1,54 @@ +--- +title: Memory Variables +slug: guides/templates/variables +--- + + +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. + + +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 + + +Reset the state of the simulated agent by clicking the "Flush Simulation" 🔄 button. + + +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.mdx new file mode 100644 index 00000000..905e64c6 --- /dev/null +++ b/fern/pages/cloud/versions.mdx @@ -0,0 +1,41 @@ +--- +title: Versioning Agent Templates +slug: guides/templates/versioning +--- + + +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. + + +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 '{}' +```