Set topic triggers

Note

This article describes features used in agents or agent flows powered by the standard harness.

For agents that use generative orchestration, the default topic trigger is The agent chooses. It activates when the agent determines that the topic's name and the description specified on the Trigger node match the incoming message from the user.

For agents that use classic orchestration, the default topic trigger is User says a phrase. It activates when one or more of the specified trigger phrases closely match an incoming message from a user. Learn more in Design effective trigger phrases.

Other trigger types are available that determine when a topic should be executed.

Prerequisites

Familiarize yourself with creating and editing topics.

Trigger types

Topic triggers make it possible for your agent to intercept and handle different events or incoming activities of different types. The following trigger types determine when a topic should trigger.

Tip

When a user sends a message to an agent, the payload is a message of type activity. Agents can receive activities of other types depending on what happens in the chat or other events.

For example, Microsoft Teams sends hidden invoke activities, which represent a user action, such as interacting with a message extension.

Type Description
The agent chooses Available for agents that use generative orchestration. Fires when the agent determines that the topic's name and description specified on the Trigger node match the incoming message from the user.
User says a phrase Available for agents that use classic orchestration. Fires when one or more of the trigger phrases match the incoming message from a user.
A message is received Fires when a message activity—the most common type of activity—is received. Received when a user types or says something to the agent.
A custom client event occurs Fires when an event activity is received. By default, all event activities are responded to. Use the Event name property within the trigger properties to filter for a specific event.
An activity occurs Fires when an activity of any type is received. You can optionally set the Activity type property in the trigger properties to filter for a specific activity type.
The conversation changes Fires when a conversation update activity is received. For example, Teams sends an activity of this type when a user joins a conversation.
It's invoked Fires when an invoke activity is received. Most commonly received from the Teams channel—for example, when the user interacts with a message or search extension in Teams.
It's redirected to Fires when the topic is called explicitly by another topic. Set the desired inactivity time using the Inactivity duration property in the trigger properties.
The user is inactive for a while Fires when the user didn't interact with the agent after a configured period of time.
A plan completes Available for agents that use generative orchestration. Fires when the agent finishes executing all planned steps to respond to a user query or autonomous trigger.
An AI-generated response is about to be sent Available for agents that use generative orchestration. Fires when the agent generates a response for a user after calling one or more topics, tools, or knowledge sources. Use the Response.FormattedText system variable to see the generated response. Set the ContinueResponse variable to false if you want to prevent the orchestration response being sent (that is, if you modify the message and send your own using a Message node).

Change the trigger for a topic

  1. Go to the Topics page for your agent, and open the topic you want.

  2. Hover over the box of the Trigger node and select the Change trigger icon.

    Screenshot showing the location of the 'Change trigger' icon on a Trigger node.

  3. Select the appropriate type of trigger for your topic.

  4. For the The agent chooses trigger, describe when your agent should use this topic.

  5. Select the three dots (…) of the Trigger node, and then select Properties. The properties panel for the specified trigger type appears.

  6. Set the applicable properties for your topic trigger:

Phrases

In agents that use classic orchestration, specify phrases to trigger topics configured with the User says a phrase trigger.

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

  2. Under Add phrases, enter a trigger phrase for your topic.

    Your agent 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 phrase you want.
    • 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.
    • Upload a file listing trigger phrases you want to add for this topic.

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

Upload trigger phrases for a topic

From the Phrases panel of a topic's Trigger node, you can add or replace the set of trigger phrases associated with the topic.

  1. Prepare a text file (maximum 3 MB) listing all trigger phrases you want to add for your topic, with each phrase on a separate line.

  2. Under Add phrases, select upload a file.

  3. In Upload a file, select the desired option:

    • If you want to add new trigger phrases for your topic, select Append.
    • To replace all existing trigger phrases with the list from your file, select Replace.
  4. Drop your file onto the window. Alternatively, select click to browse, navigate to your file, and select it.

  5. Review the trigger phrases that appear, and then select Add.

  6. Save your topic.

Download trigger phrases for a topic

From the Phrases panel of a topic's Trigger node, you can download the set of trigger phrases associated with the topic.

  1. Under Add phrases, select download.

  2. Save the resulting text file, or open it in a text editor to review its content. Each trigger phrase appears on a separate line.

Trigger condition

Specify conditions that must be met for the trigger to fire. For example, you might want the trigger to fire only if the channel used by an employee is Microsoft Teams.

Screenshot of a trigger condition.

If you need more complex conditions, switch to the Power Fx formula editor: select Builder and then select Formula.

Screenshot showing the option to go to the formula editor.

Trigger priority

More than one trigger can fire for a single incoming activity, such as a message. The trigger type determines the order the triggers fire.

Order of execution:

  1. An activity occurs
  2. A message is received / A custom client event occurs / The conversation changes / It's invoked
  3. The agent chooses / User says a phrase

If there are more than one qualifying triggers of the same type, the system executes the triggers in the order of creation (oldest first).

You can set the Priority property to explicitly determine the order of execution.