Skip to main content

Best Practices

When sending messages using AI, Teams recommends a number of best practices to help with both user and developer experience.

AI-Generated Indicator​

When sending messages using AI, Teams recommends including an indicator that the message was generated by AI. This can be done by adding a addAiGenerated property to outgoing message. This will help users understand that the message was generated by AI, and not by a human and can help with trust and transparency.

message_to_be_sent = MessageActivityInput(text="Hello!").add_ai_generated()

Screenshot of outgoing agent message to user marked with 'AI generated' badge.

Gather feedback to improve prompts​

AI Generated messages are not always perfect. Prompts can have gaps, and can sometimes lead to unexpected results. To help improve the prompts, Teams recommends gathering feedback from users on the AI-generated messages. See Feedback for more information on how to gather feedback.

This does involve thinking through a pipeline for gathering feedback and then automatically, or manually, updating prompts based on the feedback. The feedback system is an point of entry to your eval pipeline.

Citations​

AI generated messages can hallucinate even if messages are grounded in real data. To help with this, Teams recommends including citations in the AI Generated messages. This is easy to do by simply using the addCitations method on the message. This will add a citation to the message, and the LLM will be able to use it to generate a citation for the user.

warning

Citations are added with a position property. This property value needs to also be included in the message text as [<position>]. If there is a citation that's added without the associated value in the message text, Teams will not render the citation

from microsoft.teams.api import MessageActivityInput, CitationAppearance

message_activity = MessageActivityInput(text=result.content).add_ai_generated()
for i, doc in enumerate(cited_docs):
    message_activity.text += f"[{i + 1}]"
    message_activity.add_citation(i + 1, CitationAppearance(name=doc["title"], abstract=doc["content"]))

Animated screenshot showing user hovering over a footnote citation in agent response, and a pop-up showing explanatory text.

Suggested actions​

Suggested actions help users with ideas of what to ask next, based on the previous response or conversation. Teams recommends including suggested actions in your messages. You can do that by using the with_suggested_actions method on the message. See Suggested actions for more information on suggested actions.

from microsoft.teams.api import CardAction, CardActionType, MessageActivityInput, SuggestedActions

suggested_actions = SuggestedActions(
    to=[activity.from_.id],
    actions=[CardAction(type=CardActionType.IM_BACK, title="Thanks!", value="Thank you so much!")],
)
message = (
    MessageActivityInput(text=chat_result.response.content)
    .add_ai_generated()
    .with_suggested_actions(suggested_actions)
)
await ctx.send(message)