Subagents in the Legacy Builder

Parts of a Subagent

A subagent includes a name, classification description, scope, instructions, and actions.

Name

The API name of the subagent. 2-3 words that describe what the subagent does in plain language.

An agent uses the subagent name to determine when to use a subagent in a conversation. The agent compares the subagent name and classification description to the user’s question or request, including the recent conversation history. Then the agent selects the best match.

When naming a subagent, keep these best practices in mind.

• Think about a particular job that the agent can do or an area of specialization or expertise.
• Use plain language that users are likely to use and understand, not technical terms. This makes it easier for the agent to match a user's question or request to a relevant subagent.
• Review other subagents that you’ve assigned to your agent to ensure that your subagent names are distinct and don’t overlap.

Example Subagent Names

Less Effective	more effective
Subagent Name: v1_CustomerInfo Explanation: The subagent name is too general to provide the agent with enough context to know how and when to use this subagent. The agent also doesn’t know what “v1” means in the context of the subagent name.	Subagent Name: Account_Management Explanation: The subagent name more specifically describes the questions and requests that the subagent can handle and uses plain language that the agent is more likely to understand.
Subagent Name: Help Explanation: The subagent name is too general to help the agent make decisions. For example, any request for help could be classified to this subagent, including requests the subagent can’t handle. It’s also possible that specific requests for technical support won’t be classified to this subagent.	Subagent Name: Technical Support Explanation: The subagent name specifies the type of help that the agent can provide and more precisely defines the scope of the subagent. The agent is more likely to select this subagent for relevant user questions and requests.

Classification Description

1–3 sentences that describe what a subagent does and the types of user requests that should be classified into this subagent. In other words, the classification description describes what user messages should trigger this subagent.

An agent uses the classification description to determine when to use a subagent in a conversation. The agent compares the subagent name and classification description to the user’s question or request, including the recent conversation history. Then the agent selects the best match.

When writing a subagent's classification description, keep these best practices in mind.

• Describe the full range of questions and requests this subagent should handle.
• Think about the ways that users ask for this type of help and include specific keywords and phrases customers typically use. Use plain language that your users are likely to use and understand, not technical terms. This makes it easier for the agent to match a question or request to a relevant subagent.
• Review other subagents that you’ve assigned to your agent to ensure that your classification descriptions are distinct and don’t overlap.

Example Classifcation Descriptions

Less Effective	More effective
Classification Description: Handle order-related questions. Explanation: An agent doesn’t necessarily understand what “order-related questions” are without additional business context, so the classification description is too general to help the agent match a customer question or request to the subagent.	Classification Description: Answer questions related to orders, shipping status, delivery times, or tracking. Help with finding order details, changing or canceling orders, and addressing order-related concerns. Explanation: The classification description lists specific scenarios customers might ask about, including key terms customers are likely to use themselves. It also details the range of order-related tasks the subagent can handle.
Classification Description: Verify before handling payment issues. Explanation: The classification description doesn’t explain what information the agent is supposed to verify or how to verify it. The agent also doesn’t necessarily understand what “payment issues” are without additional business context.	Classification Description: Verify the customer before proceeding to check payment status, obtaining payment information or updating their payment method. Explanation: The classification description better describes the verification task and redirects the agent to a different subagent. It also provides examples of payment-related tasks that involve sensitive information and require the verification step.

Scope

A specific job description that sets boundaries for your agent.

After an agent selects a subagent, the scope tells the agent what it can and can’t do with a subagent.

When writing a subagent's scope, keep these best practices in mind.

• Think about how you would explain a job to a new employee.
• Specify what your agent can do with the subagent (“Your job is to…”) and what your agent shouldn’t do with the subagent (“You can’t…, “Never…”). Explicitly defining your agent's capabilities and limits makes it more likely that your agent won't try to handle user questions and requests that aren’t relevant or appropriate for the subagent.
• When specifying your agent’s boundaries, use simple, unambiguous language to minimize the risk of misunderstanding.

Example Scope

Less effective	More effective
Scope: Help with login problems. Explanation: The scope doesn’t provide any specific information, guidelines, or examples about what the agent should or shouldn’t do with the subagent.	Scope: Your job is only to help customers who cannot log in with resetting their password or looking up their username. You cannot update account information or modify permissions. Explanation: The scope uses explicit language to specify the tasks the agent can handle with the subagent as well as the tasks the agent shouldn’t attempt to handle with the subagent.

Instructions

Guidelines that tell your agent how to handle conversations in the context of the subagent, your business case, and the conversation in general. Each instruction is a single subagent-specific guideline. Each instruction field supports up to 131,072 characters, but for best performance, we recommend simpler, shorter instructions where possible.

Important Instructions are nondeterministic and rely on an LLM for interpretation. Don’t use subagent instructions to handle critical business logic that must be consistently enforced, such as complex calculations, sensitive information processing, or multistep operations that require a specific sequence. Instead, build these requirements into the functionality of an agent action. For example, instead of adding the instruction “Don’t refund an order unless it was within 30 business days,” create a flow-based agent action that assesses the criteria for issuing a refund.

After an agent selects a subagent, it uses subagent instructions, along with the names and instructions of the associated actions, to decide what actions to run, the sequence of steps the agent should follow, and how the agent should format its responses. The agent also uses subagent instructions to understand how to handle exceptions, such as when to ask for more information or when to transfer the conversation to a representative.

Subagent instructions are so important to agent decision-making, behavior, and responses that we couldn’t fit all of the best practices on this page. See Best Practices for Subagent Instructions to learn how to use instructions to guide the agent conversation, help your agent select appropriate actions, define the format and tone of your agent’s responses, and establish clarification or escalation strategies when information is ambiguous.

Example Subagent Instructions

Less effective	More effective
Instruction: Get the customer's order details. Explanation: The instruction doesn’t give the agent any information about how or when to get the customer’s order details. The agent also may not know what order details mean in this context. So the agent won’t consistently capture the necessary information at the right time in the conversation or run related actions.	Instruction: If a customer asks for the status of an order, always offer all options to look up the status using either their email address, order date, or the order ID. Explanation: The instruction is specific about when the agent should look up order information and what information to look up. It uses language that’s similar to the names of the actions the agent can use for the task paired with the absolute term “always,” so the agent is more likely to consistently run one of these actions at the right time in the conversation.
Instruction: Use knowledge for product questions. Explanation: The instruction tells the agent to use knowledge to respond to product questions, but doesn’t tell the agent when or how. The agent also may not know what product questions mean in this context.	Instruction: For questions about product features, first identify which specific product the customer is asking about. Then use the Answer Questions with Knowledge action with the exact product name to retrieve accurate information. Explanation: The instruction provides a clear sequence of steps in a single instruction, so the agent is more likely to follow them in order. The instruction also explains how to use knowledge to generate a helpful response by identifying the action the agent should run by name, specifying information to use as input for that action, and specifying how to collect that information.
Instruction: Check if customers need help. Explanation: The instruction is intended to get the agent to ask a follow-up question, but it doesn’t tell the agent when it should follow up or give the agent enough information to generate a context-appropriate question.	Instruction: After providing information on shipping status, always ask if the customer needs help with anything else related to their order. Explanation: The instruction describes when the agent should ask a follow-up question and provides more details about the expected content of the question.

Actions

In addition to these fields, a subagent contains actions that are relevant to the subagent’s use case. Each action in a subagent is a task that your agent can perform when that subagent is selected in the conversation. For example, an Order Management subagent can contain:

• Get Order by Order ID
• Get Order by Email Address
• Look Up Return Status
• Create Return Label

How a Subagent Works

When an agent is triggered, or when a user enters a question or request in an agent conversation, an agent compares user’s input to the names and classification descriptions of all of the subagents assigned to it. The agent then classifies the task or utterance into the most relevant subagent. Based on the selected subagent’s actions and instructions, the agent can launch one or more actions. Or if the agent is chatting with a user, the agent can prompt the user for additional information (for example, a clarifying question or the required input for an action). To learn more about this process, see How Agents Created in the Legacy Builder Work.

Let's look at an example password reset subagent to see how each field guides the agent conversation.

First, the agent matches the customer’s message to the Password Reset subagent because the subagent name is related to login details and the classification description mentions “forgotten passwords,” “need credentials,” and “login problems.”

Next, the agent checks the customer's request against the subagent's scope. Although the customer asked for their login details, the scope prohibits the agent from accessing or modifying account details. Instead, the agent offers to reset the customer’s password.

The agent follows the instructions to first verify the customer’s identity by the customer’s preferred verification method. In this case, the customer prefers the email method, so the agent uses the Verify Customer Email action.

At this point, you've seen how the agent uses all of the parts of a subagent. But let's continue the conversation because the agent hasn't resolved the customer's request just yet. Next, the user receives the verification email and successfully completes the process. The agent then follows the instructions to explain the reset process and use the Send Password Reset Email action.

The customer completes the password reset process, so the agent follows the final instruction to ask if the customer needs anything else related to account access. The customer responds that this has resolved their issue, which resolves their request.