Create Guidance to give AI Agent custom instructionsUpdated a month 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 inquiries 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
• Write and format Guidance
• Test and troubleshoot Guidance

Requirements

• You must have an active Automate subscription
• You must have Lead or Admin permissions

Create a new Guidance

You can create up to 40 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
2. Select Knowledge under a connected store, then click on the Guidance tab
3. Select Create Custom Guidance
   
   
   • 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
   • Learn how to write effective Guidance
6. Make sure Available for AI Agent is toggled On, then select Create Guidance

Adding 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

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 environment 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.

• Guidance name is not descriptive → Make sure your Guidance has a descriptive name that clearly reflects the scenario when AI Agent should use it
  
  
  • ✅ Good practice → “when a shopper asks about the return policy for limited edition blue shirts”
  • ❌ Poor practice → “Limited edition blue shirts”
• Unclear resolution or conditions → Minimize ambiguity by giving AI Agent straightforward, step-by-step instructions. This ensures predictable, repeatable outcomes for the scenarios described in Guidance
  
  
  • ✅ Good practice → “when you receive a complaint from a customer, do/respond with XYZ…”
  • ❌ Poor practice → “don't reply to tickets with complaints…”
• Poor formatting → you might have written thorough instructions, but AI Agent may have trouble interpreting them without a clear structure
  
  
  • ✅ Good practice → Use bullet points for organization, number lists for sequences, and bold for emphasis.
  • ✅ Good practice → Consider using WHEN, IF and THEN statements to clearly articulate your instructions
• Avoid unsupported actions → you may be telling AI Agent to perform an unsupported action in Guidance. Learn more about unsupported actions in Guidance.