Create Guidance to give AI Agent custom instructionsUpdated 2 days ago

Guidance are custom instructions that you write for AI Agent in natural language—like how’d you’d explain something to a new teammate.

You can use Guidance to tell AI Agent how to behave and respond to specific shopper requests or scenarios. For example, you might use Guidance to tell AI Agent what to say and do when someone asks to return an order.

When AI Agent picks up a ticket, it considers Guidance before any other knowledge source or action. So while shoppers do not see Guidance directly, it plays a big role in shaping their experience with your store. Your Guidance sets up AI Agent to successfully handle shopper inquiries in a way that’s consistent with your brand.

In this article you’ll learn how to:

• Create Guidance
• Add variables to Guidance
• Refer to Actions in Guidance
• Write and format Guidance
• Test and troubleshoot Guidance

Requirements

• You must have an active AI Agent subscription
• You must have Lead, Admin or Account Owner permissions

Creating a new Guidance

You can create up to 100 Guidance for AI Agent per store connected to Gorgias. Each Guidance has a 5000 character limit.

Although AI Agent can read and understand multiple languages, we recommend that you write Guidance in English for optimal results.

1. Go to AI Agent from the main menu, then select Knowledge
   
   
   • If you have more than 1 Shopify store connected to Gorgias, use the dropdown menu to select a store
2. Click on the Guidance tab
3. Select Create Custom Guidance, or alternatively select Create from Template to get started with common scenarios for Guidance
4. Enter a descriptive name for your Guidance
   
   
   • Use specific, intent-rich titles to increase AI Agent’s ability to match your Guidance to the scenarios when it should be used
   • Think like a shopper when naming your Guidance. What question or intent are they likely to express?
5. Enter instructions for AI Agent to follow
   
   
   • Select {+} Variables to add Shopify variables
   • Select Actions to reference in Guidance
   • Learn how to write effective Guidance
6. Make sure Available for AI Agent is toggled On, then select Create Guidance

Add Shopify variables to Guidance

Variables are placeholders for specific data points that AI Agent can easily reference and understand—like Shopify orders tags, a shipping address or fulfillment status.

You can insert variables directly into Guidance to improve AI Agent’s accuracy and personalize how it responds to shoppers.

For example, if you were writing a Guidance about discount codes, you might include a statement like: IF [Tags] include “VIP”, THEN provide the shopper with the discount code VIP25

To add a variable to your Guidance:

1. Open an existing Guidance or create a new one
2. Select {+} Variables from the text editor
3. Choose a variable to insert into your Guidance

Refer to Actions in Guidance

You can reference Support Actions that you’ve created for AI Agent directly in your Guidance.

By tagging Actions in Guidance, you can write an end-to-end procedure for AI Agent that describes, in context, when an Action should be used.

For example, if you create an Action that allows AI Agent to cancel an order, you can write Guidance that instructs AI Agent on what to do before using the Action. To do this, your Guidance might look something like this:

WHEN a shopper asks to cancel their order, take the following steps:

• First, ask them if they’d rather keep their order and get a 20% discount code to apply to their next order.
• THEN, based on the response from the shopper:
  • IF they accept the discount code option, provide them with the discount code “20OFF,” thank them, then close the ticket.
  • IF they do not accept the discount code, proceed with [Use Action: Cancel Order in Shopify].

To add an Action to your Guidance:

1. Open an existing Guidance or create a new one.
2. Select Actions from the text editor.
3. Search for and select an Action to insert into your Guidance.

Writing and formatting Guidance

Like a person reading your instructions, AI Agent benefits from clearly written, well formatted text. Avoid writing everything in a single paragraph. Instead, use rich formatting like bullet points for lists, numbered steps and bolded text to break out instructions visually.

Learn more about best practices for writing Guidance.

We recommend structuring your Guidance according to WHEN, IF and THEN statements.

• WHEN → define the scenario. You can also use this as the title of your Guidance. Examples include:
  
  
  • When a shopper asks to return an order…
  • When a shopper wants to exchange an order…
  • When a shopper requests an order cancellation…
• IF → use “if statements” to add conditions or variations to the scenario. For example:
  
  
  • If the order was placed less than or equal to 15 days ago…
  • If the order was placed more than 15 days ago…
• THEN → this tells AI Agent exactly what to do when the condition in an IF statement is met. Use numbered steps for sequences. For example:
  
  
  • IF the order was placed less than or equal to 15 days ago, THEN…
    1. Tell the shopper they are eligible for a return
    2. Send the shopper a link to the return portal
    3. Tell the shopper they’ll get a prepaid return label via email once they fill out the required information in the return portal

Testing and troubleshooting Guidance

You can use AI Agent’s test feature to see if the AI correctly follows your Guidance for the intended scenario. Just make sure you’ve published your Guidance first (use the Available for AI Agent toggle).

If your Guidance doesn’t trigger or the AI doesn’t follow your instructions correctly, consider the following common fixes to troubleshoot.