Use the code editor to write and edit YAML in topics

Topics can be written and edited in the code editor, which supports the use of YAML, which stands for "YAML Ain't Markup Language." YAML is used to write configuration files, and tends to be easier to read than XML or JSON. YAML files use either the .yaml or .yml file extension. YAML files are formatted with spacing and indentation to represent data structures, such as strings, numbers, Boolean, lists, and dictionaries.

To access the code editor from a topic, select the More icon (…) and then select Open code editor.

Watch this video to get an overview of how to use YAML in the code editor:

When to use the code editor

Copilot Studio never requires you to write YAML from scratch. Instead, YAML is generated automatically when you create objects on the topic canvas. You can then either review the configuration in the code editor to better understand the settings, or you can choose to make changes to the YAML. Here are example use cases for the code editor:

• The code editor displays the complete configuration of a topic without the need to interact with individual dialog elements in the topic. It's a one-stop shop for displaying all the settings in a topic.
• Makers might choose to copy specific nodes from a topic and paste them into other topics, rather than using the Copy and Paste icons. It might be easier than selecting multiple nodes of a configuration.
• Makers might choose to update a Power Automate flow ID in YAML, rather than wait on the synchronization to the Call and Action menu.
• Makers might choose to clone and revise Question nodes or Message nodes when they're similar. However, in such cases, it's critical to ensure that all the IDs and variables remain unique. Remember to revise cloned IDs to turn them into unique IDs.
• Makers might choose to do simple revisions, such as appending a term to topic phrases, in the code editor since it can be faster to type, or copy and paste the text into the YAML code.

Understanding YAML in the code editor

The following image shows an example of a typical block of YAML.

Here's how that code applies to the corresponding topic as it appears on the canvas.

• Line 1: The type of topic
• Lines 2-3: Indicate the start of a conversational boosting topic
• Line 7: Indicates a generative answers node
• Line 9: The relevant variable
• Lines 11-12: Details about the prompt and special instructions
• Lines 20-26: Knowledge source links
• Lines 28-32: Condition group—each condition has a unique ID, along with the condition's formula details and redirects

Test YAML in the code editor

If you'd like to test out this code, perform the following steps in Copilot Studio:

1. Create an agent.

2. Go the Settings page for your agent, select Generative AI, and select Generative.

3. Go to the Topics page, select System, and select the Conversational boosting topic.

4. Open the code editor.

5. Replace the existing code with the following sample YAML code.

    kind: AdaptiveDialog
    beginDialog:
     kind: OnUnknownIntent
     id: main
     priority: -1
     actions:
       - kind: SearchAndSummarizeContent
         id: search-content
         userInput: =System.Activity.Text
         variable: Topic.Answer
         moderationLevel: Medium
         additionalInstructions: Include emojis to make responses more fun.
         publicDataSource:
           sites:
             - "www.chessusa.com/"
             - "www.chess.com/"
             - "www.lichess.org/"
   
         sharePointSearchDataSource: {}
   
       - kind: ConditionGroup
         id: has-answer-conditions
         conditions:
           - id: has-answer
             condition: =!IsBlank(Topic.Answer)
             actions:
               - kind: EndDialog
                 id: end-topic
                 clearTopicQueue: true
   

6. Select Save and close the code editor.

7. Test the agent in the Test panel by asking a chess-related question, such as, "How does a knight move?"

Related content

• YAML Ain't Markup Language (YAML™) revision 1.2.2
• YAML Checker - The YAML Syntax Validator
• YAML to JSON Converter