@microsoft/agents-activity/dist/src/entity/AIEntity.d.ts

Microsoft 365 Agents SDK for JavaScript. Activity Protocol serialization and deserialization.

/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { Activity } from '../activity';
import { Entity } from './entity';
/**
 * Supported icon names for client citations. These icons are displayed in Teams to help users
 * identify the type of content being referenced in AI-generated responses.
 */
export type ClientCitationIconName = 
/** Microsoft Word document icon */
'Microsoft Word'
/** Microsoft Excel spreadsheet icon */
 | 'Microsoft Excel'
/** Microsoft PowerPoint presentation icon */
 | 'Microsoft PowerPoint'
/** Microsoft OneNote notebook icon */
 | 'Microsoft OneNote'
/** Microsoft SharePoint site or document icon */
 | 'Microsoft SharePoint'
/** Microsoft Visio diagram icon */
 | 'Microsoft Visio'
/** Microsoft Loop component icon */
 | 'Microsoft Loop'
/** Microsoft Whiteboard icon */
 | 'Microsoft Whiteboard'
/** Adobe Illustrator vector graphics icon */
 | 'Adobe Illustrator'
/** Adobe Photoshop image editing icon */
 | 'Adobe Photoshop'
/** Adobe InDesign layout design icon */
 | 'Adobe InDesign'
/** Adobe Flash multimedia icon */
 | 'Adobe Flash'
/** Sketch design tool icon */
 | 'Sketch'
/** Source code file icon */
 | 'Source Code'
/** Generic image file icon */
 | 'Image'
/** Animated GIF image icon */
 | 'GIF'
/** Video file icon */
 | 'Video'
/** Audio/sound file icon */
 | 'Sound'
/** ZIP archive file icon */
 | 'ZIP'
/** Plain text file icon */
 | 'Text'
/** PDF document icon */
 | 'PDF';
/**
 *  Represents a Teams client citation to be included in a message.
 *
 * @remarks
 * [Learn more about Bot messages with AI-generated content](https://learn.microsoft.com/microsoftteams/platform/bots/how-to/bot-messages-ai-generated-content?tabs=before%2Cbotmessage)
 */
export interface ClientCitation {
    /**
     * Required; must be "Claim"
     */
    '@type': 'Claim';
    /**
     * Required. Number and position of the citation.
     */
    position: number;
    /**
     * Optional; if provided, the citation will be displayed in the message.
     */
    appearance: {
        /**
         * Required; Must be 'DigitalDocument'
         */
        '@type': 'DigitalDocument';
        /**
         * Name of the document. (max length 80)
         */
        name: string;
        /**
         * Stringified adaptive card with additional information about the citation.
         * It is rendered within the modal.
         */
        text?: string;
        /**
         * URL of the document. This will make the name of the citation clickable and direct the user to the specified URL.
         */
        url?: string;
        /**
         * Extract of the referenced content. (max length 160)
         */
        abstract: string;
        /**
         * Encoding format of the `citation.appearance.text` field.
         */
        encodingFormat?: 'application/vnd.microsoft.card.adaptive';
        /**
         * Information about the citation’s icon.
         */
        image?: {
            '@type': 'ImageObject';
            /**
             * The image/icon name
             */
            name: ClientCitationIconName;
        };
        /**
         * Optional; set by developer. (max length 3) (max keyword length 28)
         */
        keywords?: string[];
        /**
         * Optional sensitivity content information.
         */
        usageInfo?: SensitivityUsageInfo;
    };
}
/**
 * Sensitivity usage info for content sent to the user.
 *
 * @remarks
 * This is used to provide information about the content to the user. See {@link ClientCitation} for more information.
 */
export interface SensitivityUsageInfo {
    /**
     * Must be "https://schema.org/Message"
     */
    type: 'https://schema.org/Message';
    /**
     * Required; Set to CreativeWork;
     */
    '@type': 'CreativeWork';
    /**
     * Sensitivity description of the content
     */
    description?: string;
    /**
     * Sensitivity title of the content
     */
    name: string;
    /**
     * Optional; ignored in Teams.
     */
    position?: number;
    /**
      * Optional; if provided, the content is considered sensitive and should be handled accordingly.
      */
    pattern?: {
        /**
         * Set to DefinedTerm
         */
        '@type': 'DefinedTerm';
        inDefinedTermSet: string;
        /**
         * Color
         */
        name: string;
        /**
         * e.g. #454545
         */
        termCode: string;
    };
}
export interface AIEntity extends Entity {
    /**
     * Required as 'https://schema.org/Message'
     */
    type: 'https://schema.org/Message';
    /**
     * Required as 'Message
     */
    '@type': 'Message';
    /**
     * Required as 'https://schema.org
     */
    '@context': 'https://schema.org';
    /**
     * Must be left blank. This is for Bot Framework schema.
     */
    '@id': '';
    /**
     * Indicate that the content was generated by AI.
     */
    additionalType: ['AIGeneratedContent'];
    /**
     * Optional; if citations object is included, the  sent activity will include the citations, referenced in the activity text.
     */
    citation?: ClientCitation[];
    /**
     * Optional; if usage_info object is included, the sent activity will include the sensitivity usage information.
     */
    usageInfo?: SensitivityUsageInfo;
}
/**
 * Adds an AI entity to an activity to indicate that the content was generated by AI.
 *
 * @param activity - The activity to which the AI entity will be added. The activity's entities array will be initialized if it doesn't exist.
 * @param citations - Optional array of client citations to include with the AI-generated content.
 *                   Citations provide references to sources used in generating the content and are displayed in Teams.
 * @param usageInfo - Optional sensitivity usage information that provides context about the content's sensitivity level.
 *                   This helps users understand any special handling requirements for the content.
 *
 * @remarks
 * This function enhances the activity with metadata that helps clients (like Microsoft Teams)
 * understand that the content is AI-generated and optionally includes citations and sensitivity information.
 *
 * @example
 * ```typescript
 * import { Activity } from '../activity';
 * import { addAIToActivity, ClientCitation } from './AIEntity';
 *
 * const activity: Activity = {
 *   type: 'message',
 *   text: 'Based on the documents, here are the key findings...'
 * };
 *
 * const citations: ClientCitation[] = [{
 *   '@type': 'Claim',
 *   position: 1,
 *   appearance: {
 *     '@type': 'DigitalDocument',
 *     name: 'Research Report 2024',
 *     abstract: 'Key findings from the annual research report',
 *     url: 'https://example.com/report.pdf',
 *     image: {
 *       '@type': 'ImageObject',
 *       name: 'PDF'
 *     }
 *   }
 * }];
 *
 * // Add AI entity with citations
 * addAIToActivity(activity, citations);
 * ```
 */
export declare const addAIToActivity: (activity: Activity, citations?: ClientCitation[], usageInfo?: SensitivityUsageInfo) => void;