Create and edit topics in your Microsoft Copilot Studio copilot

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.

In Copilot Studio, a topic defines a how a copilot conversation progresses.

To author topics, you can customize provided templates, create topics from scratch, or get suggestions from existing help sites.

In Copilot Studio, a topic represents some portion of a conversational thread between a user and a copilot. You define and work with topics on an authoring canvas, which is the app itself. A topic contains one or more conversation nodes, which together define the conversational paths that a topic can take. Each node performs an action, such as sending a message or asking a question.

Often, a topic has a set of trigger phrases—phrases, keywords, and questions that a customer is likely to use that are related to a specific issue. The Copilot Studio AI uses natural language understanding, your customer's message, and the trigger phrases for all your topics to find the best topic to trigger. The message doesn't need to exactly match a topic's trigger phrases to trigger the topic. For example, a topic about store hours might include the trigger phrase check store hours. If a customer sends, "see store opening hours," Copilot Studio triggers your store hours topic.

Natural language understanding

The AI uses natural language understanding (NLU) to parse what a customer typed and find the best trigger phrase or node.

For example, a user might type "Open hours" into your copilot. The AI matches that to the Store hours topic, begins a conversation that asks which store the customer is interested in, and then displays the hours the store is open.

The Test copilot pane shows how the copilot conversation progresses at every step. You can use the Test copilot pane to fine-tune a topic without having to exit the Copilot Studio portal.

For copilot and topic limits, see Quotas, limits, and configuration values.

Prerequisites

Topics

Topic types

A copilot can include two types of topics, system and custom. Every new copilot starts with a set of system and custom topics.

  • System topics support essential behaviors, such as a custom request to speak to a person or end the conversation. Some system topics have trigger phrases, which you can customize to fit your copilot's needs.

    • You can't create system topics.
    • You can't delete system topics, but you can disable them.
    • You can make changes to system topics. However, until you're comfortable creating end-to-end copilot conversations, we don't recommend editing the system topics.

    For more information, see Use system topics.

  • Custom topics cover common behaviors, such as greeting a customer, ending a conversation, or restarting conversation.

    • You can make changes to the starting custom topics or remove them from your copilot entirely.
    • All topics that you create are custom topics.

Create a topic

  1. Open your copilot from the list on the Copilot page. For better visibility, close the Test copilot window for now.

  2. From the Topics & Plugins page, select + Add > Topic > From blank.

    Screenshot of the Copilot Studio Topics & Plugins page with +Add highlighted.

  3. On the Trigger node, select Edit under Phrases twice to see the Add phrases section.

    Screenshot of the topic authoring canvas showing the Trigger node and the Add phrases section.

  4. Under Add phrases, enter text to add a trigger phrase for your topic.

    Your copilot needs 5 to 10 trigger phrases to train the AI to understand your customers' responses. To add more trigger phrases, you can either:

    • Select the "+" next to the text field.
    • Paste a set of trigger phrases, each one on a separate line.
    • Type a set of trigger phrases, pressing Shift+Enter after each one to place it on a separate line.
    • Select Enter to complete adding the phrase(s).

    You can include punctuation in a trigger phrase, but it's best to use short phrases rather than long sentences.

  5. Select Details to open the Topic details pane.

    Screenshot of the topic authoring canvas with Details highlighted.

  6. Add your copilot topic details:

    • Add a Name to identify the topic, such as "Store hours". The Topics page lists all the topics defined in your copilot, by this name. A customer might see the topic name if the copilot can't determine which topic matches the customer's message.

    • The Description is never shown to users. Use it to describe the purpose of the topic for yourself and other copilot makers on your team.

  7. Select Save at the top of the page to save your changes and add the topic to the topics list.

Design a topic conversation path

When you create a topic, a Trigger node is inserted for you on the Topics & Plugins page. You can add more nodes to control the conversation.

  1. Select a topic from the Topics & Plugins page of your copilot.

  2. Select the "+" to add another node, which might be shown before or after any node. The locations you can add a node give you flexibility to edit any part of a conversation.

    Screenshot of the Add node button in the Microsoft Copilot Studio authoring canvas.

  3. Select a node type to insert the node.

    Here are the types of nodes you can insert in a topic:

    Option Description
    Send a message Send the customer a message.
    Ask a question Ask the customer a question.
    Ask with adaptive card Create a JSON snippet to exchange with other apps.
    Add a condition Branch your conversation based on a condition.
    Variable management Set a value or parse a new or existing variable.
    Topic management Redirect, transfer, or end the topic or conversation.
    Call an action Call a flow like Power Automate or Excel Online.
    Advanced Generative answers, HTTP requests, events, and more.

    Screenshot of node types to insert after a Trigger node.

Add a question node

The Question node can prompt a user for information and store their response in a variable for use later in the conversation.

The node allows you to choose the type of information to collect, such as a multiple-choice answer, a prebuilt entity, or a custom entity. Question behavior properties allow you to control the behavior of the node, such as what to do when the user enters an invalid response.

Just like Message nodes, Question nodes can include images, videos, cards, quick replies, and message variations. For more information, see Send a message.

Here's how to build a Question node:

  1. Select the "+" on any node, then select Ask a question. The Question node form appears.

    Screenshot of a new Question mode.

  2. In the Enter a message box, type the question you want to ask.

  3. Select the menu under Identify, then either create or select an option. Your chosen entity determines what the copilot should listen for in the user's response. For more information on entities, see Learn how to use entities in a conversation.

  4. Depending which Identify option you selected, you may have more properties you need to set.

    For example, if you choose Multiple choice options, select + New option under Options for user to add choices the user can select. Each choice is presented as a multiple-choice button in a conversation, but users can also type their answers.

  5. Select the variable name under Save response as and change the name of the default variable to something meaningful, like customerName or bookingDate. You can set the scope of the variable in the Variable properties pane as well.

    Screenshot of a new variable created for a Question node.

Configure question behavior

Question behavior properties allow you to control how the copilot responds to an invalid response or how it validates user input.

  1. On the Question node, select the ... to see the the Node Menu, and then select Properties. The Question properties pane appears.

  2. In the Question properties pane, select Question behavior to open the Question behavior pane.

    Screenshot of properties pane.

The Question behavior pane is where you can adjust behaviors like prompts, validations, and interruptions. Let's examine a few behaviors.

Skip behavior

Skip behavior determines what the copilot should do if the question node's variable already has a value from earlier in the conversation.

  • Allow question to be skipped: Skip the question if the variable has a value.
  • Ask every time: Ask the question even if the variable has a value.

Reprompt

Reprompt determines how your copilot reacts if it doesn't get a valid answer from the user. You can tell it to try again once, twice, or move on without getting an answer. To customize what your copilot does when it moves on, see No valid entity found in the Question behavior pane. You can also change the prompt to give the user more context.

  • How many reprompts: The number of times your copilot tries to get a valid answer. Repeat up to 2 times is the default. You can also select Repeat once or Don't repeat.

  • Retry prompt: To change the message, select Customize, and then enter the new prompt.

Entity validation

By default, the Question node checks for a valid response based only on the entity you selected. Additional entity validation allows you to add criteria to the basic test. For example, the Question node accepts any numeric value when it identifies a number, but you might want to set it to less than 10. You can also change the prompt to help the user enter a valid response.

  • Condition: Enter a Power Fx formula that returns a boolean value (true or false); for example, Topic.Var1 < 10

  • Condition not met prompt: When the condition isn't met, you can provide a message. Select Customize and enter the new prompt.

No valid entity found

No valid entity found determines what happens when your copilot stops trying to get a valid response from the user. You can escalate to a human agent or provide a default value. You can also change the prompt to let the user know.

  • Action if no entity found:

    • Escalate: Redirect the user to the Escalate system topic. Escalate is the default.
    • Set variable to value: Set the output variable to a value and move on to the next node. Enter or select the value in Default entity value.
    • Set variable to empty (no value): Set the output variable to Blank and move on to the next node. You can use a Condition node later to check whether the variable has a value.
  • No entity found message: To change the message, select Customize, and then enter the new prompt.

Interruptions

Interruptions determine whether the user can switch to a different topic during the question.

  • Allow switching to another topic: The user can abandon the question for a new topic.

Delete a node

Select the ... to see the Node Menu, and then select Delete.

Screenshot highlighting the Node Menu button and the Delete button.

Controls for editing nodes on the canvas

You can use the authoring canvas toolbar to quickly rename the topic. Select the topic name in the toolbar, type the new name, then press Enter.

Screenshot of the topic authoring canvas with the topic name highlighted.

You can use controls on the toolbar to cut, copy, paste, and delete the selected node or selected adjacent nodes.

Screenshot of the toolbar controls for editing nodes on the authoring canvas.

The toolbar also has a control to undo an edit. Open the Undo menu to revert all actions back to the last save or to redo the previous action.

Screenshot of the Undo menu.

Paste nodes

Once you use the Cut or Copy tools to place one or more nodes on the clipboard, there are two ways to paste them in the canvas:

  • If you select a node and then select Paste, the nodes on the clipboard are inserted after the selected node.

  • If you select the "+" to see the Add node menu, then select Paste, the node on the clipboard is inserted at that location.

Edit topics with the code editor

The code editor shows the topic in YAML, a markup language that's easy to read and understand. Use the code editor to copy and paste topics from other bots, even ones created by other authors.

Important

Designing a topic entirely in the code editor and pasting complex topics isn't fully supported.

In this example, you copy and paste YAML into the code editor to quickly add a topic that asks the customer for shipping information.

  1. On the Topics page, select + New topic.

  2. In the upper-right corner of the authoring canvas, select the ... to see More options, then select Open code editor.

    Screenshot of how to open the code editor.

  3. Select and delete the contents of the code editor. Then copy and paste the following YAML code:

    kind: AdaptiveDialog
    beginDialog:
      kind: OnRecognizedIntent
      id: main
      intent:
        displayName: Lesson 3 - A topic with a condition, variables and a prebuilt entity
        triggerQueries:
          - Buy items
          - Buy online
          - Buy product
          - Purchase item
          - Order product
    
      actions:
        - kind: SendMessage
          id: Sjghab
          message: I am happy to help you place your order.
    
        - kind: Question
          id: eRH3BJ
          alwaysPrompt: false
          variable: init:Topic.State
          prompt: To what state will you be shipping?
          entity: StatePrebuiltEntity
    
        - kind: ConditionGroup
          id: sEzulE
          conditions:
            - id: pbR5LO
              condition: =Topic.State = "California" || Topic.State = "Washington" || Topic.State     = "Oregon"
    
          elseActions:
            - kind: SendMessage
              id: X7BFUC
              message: There will be an additional shipping charge of $27.50.
    
            - kind: Question
              id: 6lyBi8
              alwaysPrompt: false
              variable: init:Topic.ShippingRateAccepted
              prompt: Is that acceptable?
              entity: BooleanPrebuiltEntity
    
            - kind: ConditionGroup
              id: 9BR57P
              conditions:
                - id: BW47C4
                  condition: =Topic.ShippingRateAccepted = true
    
              elseActions:
                - kind: SendMessage
                  id: LMwySU
                  message: Thank you and please come again.
    
  4. Select Save, and then select Close code editor. The Question node now has many conditions to the question about shipping.

    Screenshot of a conversation created from YAML in the Microsoft Copilot Studio code editor.

Test and publish your copilot

Test your copilot when you make changes to your topics, to make sure everything works as expected.

After you design and test your copilot, publish it to the web, mobile or native apps, or Microsoft Bot Framework channels.