diff --git a/msteams-platform/bots/how-to/bot-messages-ai-generated-content.md b/msteams-platform/bots/how-to/bot-messages-ai-generated-content.md index 478823401d3..cc7bc0f855c 100644 --- a/msteams-platform/bots/how-to/bot-messages-ai-generated-content.md +++ b/msteams-platform/bots/how-to/bot-messages-ai-generated-content.md @@ -1,6 +1,6 @@ --- -title: Bot Messages with AI-generated Content -description: Learn how to add an AI label, sensitivity labels, citations, and feedback buttons for bots built using Teams SDK or Bot Framework SDK. +title: Bot messages with AI-generated content +description: Learn how to add an AI label, sensitivity labels, citations, and feedback buttons for bots built using Teams SDK. ms.topic: conceptual ms.localizationpriority: medium ms.date: 04/15/2026 @@ -84,30 +84,42 @@ An AI label on your bot message indicates that it’s generated by AI. While AI- ### Add AI label -If you're using **Teams SDK** to build your bot, AI label is automatically enabled for all AI-powered bot messages in the `ai` module within the `PredictedSayCommand` action. For more information, see [AIEntity interface](https://github.com/microsoft/teams-ai/blob/main/js/packages/teams-ai/src/actions/SayCommand.ts#L67). +To build your bot using **Teams SDK**, use the `addAiGenerated()` method to mark a message as AI-generated. The following code snippet shows how to enable the AI label in a bot message: -If you're using **Microsoft Bot Framework SDK** to build your bot, include `additionalType` under the `entities` array of the `message` entity object. The following code snippet shows how to enable the AI label in a bot message: +# [JavaScript](#tab/javascript) ```javascript -await context.sendActivity({ - type: ActivityTypes.Message, - text: `Hey! I'm a friendly AI bot. This message is generated by AI.`, - entities: [ - { - type: "https://schema.org/Message", - "@type": "Message", - "@context": "https://schema.org", - additionalType: ["AIGeneratedContent"], // Enables AI label - } - ] +app.message(/label/i, async ({ send }) => { + await send(new MessageActivity("Hi, this message is generated by AI").addAiGenerated()); }); ``` -| Property | Type | Required | Description | -|--|--|--|--| -| `additionalType` | Array | Yes | Enables AI label in the bot message.
Allowed value: `AIGeneratedContent` | +# [C#](#tab/csharp) + +```csharp +async Task SendAILabel(IContext context) +{ + await context.Send(new MessageActivity + { + Text = "Hi, this message is generated by AI" + }.AddAIGenerated()); +} +``` + +# [Python](#tab/python) + +```python +@app.on_message_pattern(re.compile(r"label", re.IGNORECASE)) +async def add_ai_label(ctx: ActivityContext[MessageActivity]): + await ctx.send( + MessageActivityInput( + text="Hi, this message is generated by AI", + ).add_ai_generated() + ) +``` -After you add an AI label, your bot's message shows an **AI generated** label next to the bot's name. When you hover over the AI label, a disclaimer appears stating, **AI-generated content may be incorrect.**. The AI label and disclaimer can't be customized for AI-powered bots. +--- +After you add an AI label, your bot's message shows an **AI generated** label next to the bot's name. When you hover over the AI label, a disclaimer appears stating, **AI-generated content may be incorrect.** The AI label and disclaimer can't be customized for AI-powered bots. ### Error handling @@ -162,112 +174,73 @@ Citations in your bot's messages can include the following: ### Add citations -If you're using **Teams SDK** to build your bot, citations are added to an AI-powered bot message automatically through `PredictedSayCommand` action. You can also modify the `PredictedSayCommand` action to add citations to your bot message. For more information, see [ClientCitation interface](https://github.com/microsoft/teams-ai/blob/main/js/packages/teams-ai/src/actions/SayCommand.ts#L42). - -If you're using **Bot Framework SDK** to build your bot, include `citation` under the `entities` array. Following is an example code snippet: +If you're using **Teams SDK** to build your bot, Use `addCitation()` to include in-text references and citation metadata in your message. Following is an example code snippet: -# [JavaScript](#tab/js) +# [JavaScript](#tab/javascript) ```javascript -await context.sendActivity({ - type: ActivityTypes.Message, - text: `Hey I'm a friendly AI bot. This message is generated through AI [1]`, // cite with [1], - entities: [ - { - type: "https://schema.org/Message", - "@type": "Message", - "@context": "https://schema.org", - citation: [ - { - "@type": "Claim", - position: 1, // Required. Must match the [1] in the text above - appearance: { - "@type": "DigitalDocument", - name: "AI bot", // Title - url: "https://example.com/claim-1", // Hyperlink on the title - abstract: "Excerpt description", // Appears in the citation pop-up window - text: "{\"type\":\"AdaptiveCard\",\"$schema\":\"http://adaptivecards.io/schemas/adaptive-card.json\",\"version\":\"1.6\",\"body\":[{\"type\":\"TextBlock\",\"text\":\"Adaptive Card text\"}]}", // Appears as a stringified Adaptive Card - keywords: ["keyword 1", "keyword 2", "keyword 3"], // Appears in the citation pop-up window - encodingFormat: "application/vnd.microsoft.card.adaptive", - image: { - "@type": "ImageObject", - name: "Microsoft Word" - }, - }, - }, - ], - }, -], -}) +app.message(/citation/i, async ({ send }) => { + const card = new AdaptiveCard(new TextBlock("Adaptive Card text")) + .withOptions({ version: "1.6" }); + const appearance: CitationAppearance = { + name: "AI messages bot", + url: "https://example.com/claim-1", + abstract: "Excerpt description", + text: JSON.stringify(card), + keywords: ["keyword 1", "keyword 2", "keyword 3"], + icon: "Microsoft Word", + }; + await send( + new MessageActivity("Hey I'm a friendly AI bot. This message is generated through AI [1]") + .addCitation(1, appearance) + ); +}); ``` -# [Python](#tab/python) +# [C#](#tab/csharp) -```python -@app.message("citation") -async def on_message(context: TurnContext, state: TurnState): - appearance = Appearance( - name="Understanding AI Citations in Python", - abstract=snippet("A brief extract demonstrating the integration of AI Citations in Python.", 477), - url="https://example.com/py-ai-citations", - keywords=["Python", "Citations"], - image=AppearanceImage(name="Microsoft Excel"), - usage_info=SensitivityUsageInfo( - name="Creative Work", - description="Sensitive content information for Python AI citation.", - position=1, - pattern= Pattern( - in_defined_term_set= "ColorSet", - name= "Red", - term_code= "#FF0000") - ) - ) +```csharp - # Create the client citation with a specific position and the defined appearance. - citation = ClientCitation( - position=1, - appearance=appearance - ) +async Task SendCitations(IContext context) +{ +var message = new MessageActivity +{ +Text = "Hey I'm a friendly AI bot. This message is generated through AI [1]" +}; + +message.AddCitation(1, new CitationAppearance +{ + Name = "AI messages bot", + Url = "https://example.com/claim-1", + Abstract = "Excerpt description", + Keywords = new List { "keyword 1", "keyword 2", "keyword 3" }, + Icon = CitationIcon.MicrosoftWord +}); + +await context.Send(message); +} +``` - # Create the AIEntity, including the citation and overall sensitivity usage information. - ai_entity = AIEntity( - additional_type=["AIGeneratedContent"], - citation=[citation], - usage_info=SensitivityUsageInfo( - name="Creative Work", - description="Overall message sensitivity information for AI citations.", +# [Python](#tab/python) + +```python +@app.on_message_pattern(re.compile(r"citation", re.IGNORECASE)) +async def add_citations(ctx: ActivityContext[MessageActivity]): + await ctx.send( + MessageActivityInput( + text="Hey I'm a friendly AI bot. This message is generated through AI [1]", + ).add_citation( position=1, - pattern=Pattern( - in_defined_term_set="ColorSet", - name= "Red", - term_code="#FF0000", - ) + appearance=CitationAppearance( + name="AI messages bot", + url="https://example.com/claim-1", + abstract="Excerpt description", + text=AdaptiveCard(version="1.6", body=[TextBlock(text="Adaptive Card text")]).model_dump_json(by_alias=True, exclude_none=True), + keywords=["keyword 1", "keyword 2", "keyword 3"], + icon=CitationIconName.MICROSOFT_WORD, + ), ) ) - - # Use the helper function to format citation tags within a sample message. - sample_text = "This is an AI-generated message with citation [doc1]." - formatted_text = format_citations_response(sample_text) - print("Formatted Text:", formatted_text) - - # Retrieve citations used in the formatted text. - used_citations = get_used_citations(formatted_text, [citation]) - print("Used Citations:", used_citations) - print("AI Entity:", ai_entity) - await context.send_activity( - Activity( - type=ActivityTypes.message, - text=formatted_text, - entities=[ - AIEntity( - citation=(list(used_citations) if used_citations else []), - additional_type=["AIGeneratedContent"], - ), - ], - ) - ) - - return True ``` --- @@ -331,33 +304,42 @@ Feedback buttons are located at the footer of the bot’s message and include a ### Add feedback buttons -For a bot built using **Teams SDK**, Teams enables feedback buttons for all bot messages when `enable_feedback_loop` is set to `true` in the `ai` module. +To enable feedback buttons in a bot built using **Teams SDK**, use the `addFeedback()` method on the message activity. + +# [JavaScript](#tab/javascript) ```javascript -export const app = new Application({ - ai: { - planner: planner, - enable_feedback_loop: true - }, +app.message(/feedback/i, async ({ send }) => { + + await send(new MessageActivity("This is an example of a feedback button - this helps to provide feedback for a message").addFeedback()); + +}); ``` -For more information, see the [const app variable](https://github.com/microsoft/teams-ai/blob/main/js/samples/04.ai-apps/h.datasource-azureOpenAI/src/app.ts#L65). +# [C#](#tab/csharp) -After you enable feedback buttons, all `SAY` commands from the bot have `feedbackLoopEnabled` in the `channelData` object automatically set to `true`. +```Csharp +async Task SendFeedbackButtons(IContext context) +{ +await context.Send(new MessageActivity("This is an example of a feedback button - this helps to provide feedback for a message") +.AddFeedback()); +} +``` -To enable feedback buttons in a bot built using **Bot Framework SDK**, define a `feedbackLoop` object under the `channelData` object of your bot message. +# [Python](#tab/python) -```javascript -await context.sendActivity({ - type: ActivityTypes.Message, - text: `Hey! I'm a friendly AI bot!`, - channelData: { - feedbackLoop: { // Enable feedback buttons - type: "custom" - }, -}); +```python +@app.on_message_pattern(re.compile(r"feedback", re.IGNORECASE)) +async def add_feedback_buttons(ctx: ActivityContext[MessageActivity]): +await ctx.send( +MessageActivityInput( +text="This is an example of a feedback button - this helps to provide feedback for a message", +).add_feedback('custom') +) ``` +--- + | Property | Type | Required | Description | |--|--|--|--| | `feedbackLoop` | Object | ✔️ | Enables feedback buttons in the bot's message. | @@ -382,53 +364,14 @@ You must respond to this invoke call with a dialog (referred to as task modules ### Handle feedback -The bot receives user input from the feedback form through a bot invoke flow. For bots built using **Teams SDK**, the bot invoke request is automatically handled. To handle feedback, use the `app.feedbackLoop` method to register a feedback loop handler to be called when the user provides feedback. +The bot receives user input from the feedback form through a bot invoke flow. For bots built using **Teams SDK**, the bot invoke request is automatically handled. Handle user feedback using the `message.submit.feedback` event. ```javascript -app.feedbackLoop(async (_context: TurnContext, _state: TurnState, feedbackLoopData: FeedbackLoopData) => { - // custom logic here... -}); +app.on("message.submit.feedback", async (context) => { + // custom logic here... +}); ``` -For more information, see the [asynchronous callback function](https://github.com/microsoft/teams-ai/blob/main/js/samples/04.ai-apps/h.datasource-azureOpenAI/src/app.ts#L111). - -For a bot built using **Bot Framework SDK**, you must have an `onInvokeActivity` handler to process the feedback. Ensure that you return a status code `200` with an empty JSON object as a response. - -The following code snippet shows how to handle feedback received in a bot invoke and return a response with the status code `200`: - -```javascript -public async onInvokeActivity(context: TurnContext): Promise { - try { - switch (context.activity.name) { - case "message/submitAction": - console.log('Your feedback is ' + JSON.stringify(context.activity.value)) - // Your feedback is {"actionName":"feedback","actionValue":{"reaction":"like","feedback":"{\"feedbackText\":\"This is my feedback.\"}"}} - return CreateInvokeResponse(200, {}); - default: - return { - status: 200, - body: `Unknown invoke activity handled as default- ${context.activity.name}`, - }; - } - } catch (err) { - console.log(`Error in onInvokeActivity: ${err}`); - return { - status: 500, - body: `Invoke activity received- ${context.activity.name}`, - }; - } - } - - export const CreateInvokeResponse = ( - status: number, - body?: unknown - ): InvokeResponse => { - return { status, body }; - }; -``` - -Store the feedback by saving message IDs and content of messages your bot sends and receives. When your bot gets an invoke request with feedback, match the message ID with the corresponding feedback. - > [!NOTE] > Teams doesn't store or process feedback. It doesn't provide an API or a storage mechanism. @@ -438,7 +381,7 @@ If a user uninstalls your bot and still has access to the bot chat, Teams remove | Error code | Description | | --- | --- | -| 400 | `message/submitAction` invoke response isn't empty. | +| 400 | `message.submit.feedback` event app.message(/label/i, async ({ send }) => { response isn't empty. | ## Sensitivity label @@ -459,9 +402,7 @@ Bot responses might contain confidential information or be accessible only to ce ### Add sensitivity label -For bots built using **Teams SDK**, sensitivity label can be added through `PredictedSayCommand` action. For more information, see [SensitivityUsageInfo interface](https://github.com/microsoft/teams-ai/blob/main/js/packages/teams-ai/src/types/AIEntity.ts#L46). - -For bots built using **Bot Framework SDK**, add a sensitivity label to your bot message by modifying the message to include `usageInfo` in the `entities` object. +For bots built using **Teams SDK**, add a sensitivity label to your bot message by modifying the message to include `usageInfo` in the `entities` object. The following code snippet shows how to add sensitivity labels to both bot messages and citation reference: @@ -544,26 +485,11 @@ After you add the sensitivity label, your bot message displays a shield icon. Us | 400 | Citation level `usageInfo.@id` value doesn't match the message level `usageInfo.@id` in at least one instance. | | 400 | There are multiple citation-level `usageInfo` properties with the same `@id`, but their `name` and `description` properties are different. | -## Modify `PredictedSayCommand` - -For a bot built using Teams SDK, the `PredictedSayCommand` provides control on how AI label, citation, feedback button, and sensitivity label are added to the bot's activity. Following is the code snippet to modify `PredictedSayCommand`: - -```JavaScript -app.ai.action(AI.SayCommandActionName, async (context, state, data, action) => { - // custom logic here... - await context.sendActivity(data.content); - return ""; -}); -``` - -For more information about `PredictedSayCommand`, see [PredictedSayCommand interface](/javascript/api/%40microsoft/teams-ai/predictedsaycommand?view=msteams-client-js-latest&preserve-view=true). - -## Code samples +## Code sample -| Sample name | Description | Node.js | .NET | -|:--|--|--| -| Teams conversation bot | This sample app displays the AI label, citation, feedback buttons, and sensitivity label in messages. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-conversation/nodejs) | NA | -| Azure OpenAI on your data | This conversational bot uses Teams SDK and contains the AI label, feedback buttons, sensitivity label, and citation in its generated messages. | NA | [View](https://github.com/microsoft/teams-ai/tree/main/dotnet/samples/08.datasource.azureopenai) | +| **Sample Name** | **Description** | **Node.js** | **.NET** | **Python** | +|---------------|--------------|--------|-------------|--------| +| Teams conversation bot | This sample app displays the AI label, citation, feedback buttons, and sensitivity label in messages. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-ai-messages/nodejs/bot-ai-messages) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-ai-messages/dotnet/bot-ai-messages) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/TeamsSDK/bot-ai-messages/python/bot-ai-messages) ## See also diff --git a/msteams-platform/includes/teams-ai-lib-v2-rec.md b/msteams-platform/includes/teams-ai-lib-v2-rec.md index 0b4ec0fb5e7..80490cea70b 100644 --- a/msteams-platform/includes/teams-ai-lib-v2-rec.md +++ b/msteams-platform/includes/teams-ai-lib-v2-rec.md @@ -1,6 +1,6 @@ > [!IMPORTANT] > > - Teams AI library is now renamed to Teams SDK. -> - Teams AI library v1 is deprecated. We recommend that you upgrade your agents to use the updated [Teams SDK](/microsoftteams/platform/teams-ai-library/welcome). +> - Teams AI library v1 is deprecated. We recommend that you upgrade your agents to use the updated [Teams SDK](/microsoftteams/platform/teams-sdk/getting-started/quickstart). > > Teams SDK is now generally available for JavaScript and C#, supports Python in developer preview. It provides a simplified SDK, support for Model Context Protocol (MCP), Agent-to-Agent communication (A2A), and streamlined tools to enable developers to build intelligent agents for Teams.