Create and edit topics

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. 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. Copilot Studio copilots use 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 enters "see store opening hours," this phrase triggers your store hours topic.

Prerequisites

Natural language understanding

A copilot 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." The copilot 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.

Topics in Copilot Studio

Topic types

A copilot can include two types of topics, system, and custom topics. Every new copilot starts with a set of predefined 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 complete copilot experiences, we don't recommend editing the system topics.

    For more information, see Use system topics.

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

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

Node types

The following types of node are available:

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, parse a value, or clear all variables.
Topic management Redirect, transfer, or end the topic or conversation.
Call an action Call a flow like Power Automate or Excel Online, or use a connector or a plugin.
Advanced Generative answers, HTTP requests, events, and more.

Create a topic

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

  2. On the top menu bar, select Topics.

  3. Select Add a topic, and select From blank.

    A Trigger node appears on an otherwise blank topic authoring canvas.

  4. Select the More icon () of the Trigger node, and then select Properties. The On Recognized Intent properties panel appears.

  5. In the On Recognized Intent properties panel, select the Phrases area. The Phrases secondary panel appears.

  6. Under Add phrases, enter 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 Add icon next to the text field, and enter the desired phrase.
    • Paste a set of trigger phrases, each one on a separate line, and select Enter.
    • Type a set of trigger phrases, pressing Shift+Enter after each one to place it on a separate line, and select Enter.

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

  7. Select Details on the toolbar to open the Topic details panel.

  8. Add your copilot topic details:

    • Enter a name to identify the topic, such as "Store hours." The Topics page lists all the topics defined in your copilot, by this name.
    • If desired, enter a display name that your copilot will show to the customer when it can't determine which topic matches the customer's message.
    • If desired, use the Description field to describe the purpose of the topic for yourself and other copilot makers on your team. Customers never see topic descriptions.
  9. Select Save on the top menu bar to save your topic.

Important

Avoid using periods (.) in your topic names. It isn't possible to export a solution that contains a copilot with periods in the name of any of its topics.

Design a topic conversation path

When you create a topic, a Trigger node automatically appears on the authoring canvas. You can then add different types of nodes to achieve the desired conversation path for your topic.

To add a node after another node or between two nodes on your topic authoring canvas:

  1. Select the Add node icon below the node under which you want to add a new node.

  2. Select the desired node type from the list that appears.

    Screenshot of the options available for selection to insert a node after a Trigger node.

Delete a node

Select the menu icon () of the node you want to delete, and then select Delete.

Controls for editing nodes on the canvas

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.

Add input and output parameters for a topic

Topics can have input and output parameters. When a topic redirects to another topic, you can use these parameters to pass information between the topics.

Additionally, if your copilot uses generative mode, it can automatically fill topic inputs from the conversation context, or after generating questions to gather values from users. This behavior is similar to how generative slot filling works for actions.

To learn more about input and output parameters for topics, see Manage topic inputs and outputs.

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 + Create > From blank.

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