Share via

Use the code editor to write and edit YAML in topics

  • Article

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.

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:

Important

All makers can leverage the code editor to visualize a single page snapshot of the full configuration of the current topic. Developers and advanced users might choose to design and edit within the code editor. However, it's recommended that caution is used when making revisions in the code editor, because errors in punctuation and other syntax patterns might result in complex error messages, and might break the current conversation. Please be advised that technical support teams can't assist in remediating code editor errors. Therefore, if you're a novice in revising YAML, make a copy of the topic before making any changes.

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. The following are some examples for using the code editor:

  • The code editor displays the complete configuration of a topic without the need to interact or navigate the individual dialogs in the topic. It's a one-stop-shop for displaying all the settings in a dialog.
  • Makers might choose to copy specific nodes from a topic and paste them into other topics, rather than using the copy/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 questions or messages when they're similar. However, in this case, it's critical to ensure that all the IDs and variables remain unique. In this scenario, remember to revise cloned IDs into unique IDs.
  • Makers might choose to do simple revisions, such as appending a term to Topic Phrases, within the code editor since you can type, or copy and paste the text into the YAML.

Understanding YAML in the code editor

The following code is an example of a typical block of YAML. For more information about how that code applies to the dialog in the canvas, see descriptions.

YAML

Screenshot of the code editor, displaying a block of sample code.

Descriptions

  • Line 1: The type of dialog
  • Line 2-3: Indicates the start of a conversational boosting system topic
  • Line 7: Indicates a generative answers node
  • Line 10: The relevant variable
  • Line 11-13: Details about the prompt and special instructions
  • Line 14-21: knowledge source links
  • Line 23-27: 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 a sample copilot.

  2. In the copilot's settings, select the Generative AI tab and select Generative (preview).

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

  4. Open the code editor.

  5. Copy the sample YAML code in this article and paste it in place of the existing Conversational boosting topic's 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
      tone: Friendly
      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 copilot in the Test pane by asking a chess-related question, such as, "How does a knight move?"

Related content