Best Practices for Subagent Instructions in the Legacy Builder

Build sensitive or deterministic business rules into the logic of an action itself, not the subagent instructions.

Instructions are nondeterministic and rely on an LLM for interpretation. They don’t replace the need for coded business rules. Instead, build these requirements into the functionality of the reference action itself. 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.

Keep instructions as minimal as possible.

Agents tend to perform best when instructions are simpler and shorter. Long instructions or too many instructions can lead to inconsistent or slow performance and complicated troubleshooting.

• Start with the fewest instructions necessary for an agent to perform as expected. Add instructions one by one as you simulate user conversations for different use cases, and then carefully test for regressions between each change.
• Before adding an instruction, review your preexisting instructions for overlap or differing advice. Contradicting instructions can cause errors and degrade performance.
• If your agent isn’t performing as expected, start by paring down your instructions. Reducing the number and complexity of instructions can help your agent reach consistent baseline functionality.

Each instruction field supports up to 131,072 characters.

Use instructions to give your agent necessary business context.

Agents don't necessarily understand your business terms, such as “lead qualification” or “AHT,” even if those terms are common in your industry. Agents also don’t necessarily understand how more general terms, like “login problems” or “help with accounts” are used by your customers and handled in your business. In general, it helps to be explicit and provide examples.

• Define terms in plain language and provide examples. For example, “"Promo codes are used for discounts during checkout, while registration codes are used to register products for warranty."
• Provide decision criteria to help your agent choose between similar options. For example, “If the customer has access to their email, use the Email Password Reset action. If the user does not have access to their email use the Security Question Verification action."
• Clearly specify what actions to use in which situations. For example, “"Use the Track Order action when customers ask about package location or delivery dates."

Don’t overload your instructions with long lists of examples. Concise, representative examples for common use cases and terminology are more effective. For example, “When using the Answer Questions with Knowledge action, include the device type in the search query (i.e., iOS or Android).” Shorter examples are easier for the agent to understand and help reduce latency.

Be explicit about any expected sequence of instructions or any conditions a conversation must meet for an agent to apply an instruction.

Agents don’t follow subagent instructions in the order they appear in the Subagent Configuration tab, so follow these steps instead.

• Put sequential steps in a single instruction field and use explicit order words, such as “First, do X... Second, do Y... Finally, do Z…” For example, “First verify the customer's identity using the Verify Customer action, then provide account information."
• Limit a sequential instruction to a few simple steps. If your instruction is too complex, the agent can follow the steps inconsistently or out of sequence.

If your agent doesn’t reliably follow the expected sequence of steps, you can use more deterministic solutions. You can apply a filter to one or more subagents or actions, so the subagent or instruction is only available to the agent once the conditions you specify are met. Or you can build the logic into an agent action itself.

Be mindful of language choice.

LLMs are sensitive to language choice, so aim to create plain language instructions that are precise, detailed, and direct.

• Use absolutes only when you mean it. In general, an agent tends to strictly follow strong language like “always” and “never.” For example, you can use "always" to make sure that your agent calls actions that provide time-sensitive information, like case status updates, in real-time. That way, users receive the most current information.
• Avoid jargon where possible. Your users are more likely to use plain language when chatting with an agent, so including plain language in your instructions makes it easier for your agent to understand your user’s questions or requests.
• Use language consistently throughout all of your instructions. When language is ambiguous, an agent can apply instructions inconsistently or incorrectly. For example, instead of writing “Check the client’s info” in one instruction and “verify the customer details” in another, use the term “customer” in both and identify specific actions by name.