@microsoft/agents-activity package

Adds an AI entity to an activity to indicate that the content was generated by AI.

Example

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);

function addAIToActivity(activity: Activity, citations?: ClientCitation[], usageInfo?: SensitivityUsageInfo)

Parameters

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.

Creates a new Logger instance with the specified namespace.

function debug(namespace: string): Logger

Parameters

Returns

A new Logger instance

Error definitions for the Activity system. This contains localized error codes for the Activity subsystem of the AgentSDK.

Each error definition includes an error code (starting from -110000), a description, and a help link pointing to an AKA link to get help for the given error.

Usage example:

throw ExceptionHelper.generateException(
  Error,
  Errors.InvalidActivityTypeUndefined
);

ActivityErrors: {[key: string]: AgentErrorDefinition}

Type

Zod schema for validating an Activity object.

activityZodSchema: z.ZodObject<{ action: z.ZodOptional<z.ZodString>, attachmentLayout: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["list", "carousel"]>, z.ZodString]>>, attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{ content: z.ZodOptional<z.ZodUnknown>, contentType: z.ZodString, contentUrl: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, thumbnailUrl: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { content?: unknown, contentType: string, contentUrl?: string, name?: string, thumbnailUrl?: string }, { content?: unknown, contentType: string, contentUrl?: string, name?: string, thumbnailUrl?: string }>, "many">>, callerId: z.ZodOptional<z.ZodString>, channelData: z.ZodOptional<z.ZodAny>, channelId: z.ZodOptional<z.ZodString>, code: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["unknown", "completedSuccessfully", "userCancelled", "agentTimedOut", "agentIssuedInvalidMessage", "channelFailed"]>, z.ZodString]>>, conversation: z.ZodOptional<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, conversationType: z.ZodOptional<z.ZodString>, id: z.ZodString, isGroup: z.ZodOptional<z.ZodBoolean>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }>>, deliveryMode: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["normal", "notification", "expectReplies", "ephemeral"]>, z.ZodString]>>, entities: z.ZodOptional<z.ZodArray<z.ZodObject<{ type: z.ZodString }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">>, "many">>, expiration: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodEffects<z.ZodString, Date, string>]>>, from: z.ZodOptional<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, agenticAppBlueprintId: z.ZodOptional<z.ZodString>, agenticAppId: z.ZodOptional<z.ZodString>, agenticUserId: z.ZodOptional<z.ZodString>, id: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }>>, historyDisclosed: z.ZodOptional<z.ZodBoolean>, id: z.ZodOptional<z.ZodString>, importance: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["low", "normal", "high"]>, z.ZodString]>>, inputHint: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["acceptingInput", "ignoringInput", "expectingInput"]>, z.ZodString]>>, label: z.ZodOptional<z.ZodString>, listenFor: z.ZodOptional<z.ZodArray<z.ZodString, "many">>, localTimestamp: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodEffects<z.ZodString, Date, string>]>>, localTimezone: z.ZodOptional<z.ZodString>, locale: z.ZodOptional<z.ZodString>, membersAdded: z.ZodOptional<z.ZodArray<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, agenticAppBlueprintId: z.ZodOptional<z.ZodString>, agenticAppId: z.ZodOptional<z.ZodString>, agenticUserId: z.ZodOptional<z.ZodString>, id: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }>, "many">>, membersRemoved: z.ZodOptional<z.ZodArray<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, agenticAppBlueprintId: z.ZodOptional<z.ZodString>, agenticAppId: z.ZodOptional<z.ZodString>, agenticUserId: z.ZodOptional<z.ZodString>, id: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }>, "many">>, name: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["ContinueConversation", "CreateConversation"]>, z.ZodString]>>, reactionsAdded: z.ZodOptional<z.ZodArray<z.ZodObject<{ type: z.ZodUnion<[z.ZodEnum<["like", "plusOne"]>, z.ZodString]> }, "strip", z.ZodTypeAny, { type: string }, { type: string }>, "many">>, reactionsRemoved: z.ZodOptional<z.ZodArray<z.ZodObject<{ type: z.ZodUnion<[z.ZodEnum<["like", "plusOne"]>, z.ZodString]> }, "strip", z.ZodTypeAny, { type: string }, { type: string }>, "many">>, recipient: z.ZodOptional<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, agenticAppBlueprintId: z.ZodOptional<z.ZodString>, agenticAppId: z.ZodOptional<z.ZodString>, agenticUserId: z.ZodOptional<z.ZodString>, id: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }>>, relatesTo: z.ZodOptional<z.ZodObject<{ activityId: z.ZodOptional<z.ZodString>, agent: z.ZodNullable<z.ZodOptional<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, agenticAppBlueprintId: z.ZodOptional<z.ZodString>, agenticAppId: z.ZodOptional<z.ZodString>, agenticUserId: z.ZodOptional<z.ZodString>, id: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }>>>, channelId: z.ZodString, conversation: z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, conversationType: z.ZodOptional<z.ZodString>, id: z.ZodString, isGroup: z.ZodOptional<z.ZodBoolean>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }>, locale: z.ZodOptional<z.ZodString>, serviceUrl: z.ZodOptional<z.ZodString>, user: z.ZodOptional<z.ZodObject<{ aadObjectId: z.ZodOptional<z.ZodString>, agenticAppBlueprintId: z.ZodOptional<z.ZodString>, agenticAppId: z.ZodOptional<z.ZodString>, agenticUserId: z.ZodOptional<z.ZodString>, id: z.ZodOptional<z.ZodString>, name: z.ZodOptional<z.ZodString>, properties: z.ZodOptional<z.ZodUnknown>, role: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["user", "bot", "skill", "agenticAppInstance", "agenticUser"]>, z.ZodString]>>, tenantId: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }>> }, "strip", z.ZodTypeAny, { activityId?: string, agent?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } | null, channelId: string, conversation: { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, locale?: string, serviceUrl?: string, user?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } }, { activityId?: string, agent?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } | null, channelId: string, conversation: { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, locale?: string, serviceUrl?: string, user?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } }>>, replyToId: z.ZodOptional<z.ZodString>, semanticAction: z.ZodOptional<z.ZodObject<{ entities: z.ZodRecord<z.ZodString, z.ZodObject<{ type: z.ZodString }, "passthrough", z.ZodTypeAny, z.objectOutputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">, z.objectInputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">>>, id: z.ZodString, state: z.ZodUnion<[z.ZodEnum<["start", "continue", "done"]>, z.ZodString]> }, "strip", z.ZodTypeAny, { entities: Record<string, z.objectOutputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">>, id: string, state: string }, { entities: Record<string, z.objectInputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">>, id: string, state: string }>>, serviceUrl: z.ZodOptional<z.ZodString>, speak: z.ZodOptional<z.ZodString>, suggestedActions: z.ZodOptional<z.ZodObject<{ actions: z.ZodArray<z.ZodObject<{ channelData: z.ZodOptional<z.ZodUnknown>, displayText: z.ZodOptional<z.ZodString>, image: z.ZodOptional<z.ZodString>, imageAltText: z.ZodOptional<z.ZodString>, text: z.ZodOptional<z.ZodString>, title: z.ZodString, type: z.ZodUnion<[z.ZodEnum<["openUrl", "imBack", "postBack", "playAudio", "showImage", "downloadFile", "signin", "call", "messageBack", "openApp"]>, z.ZodString]>, value: z.ZodOptional<z.ZodAny> }, "strip", z.ZodTypeAny, { channelData?: unknown, displayText?: string, image?: string, imageAltText?: string, text?: string, title: string, type: string, value?: any }, { channelData?: unknown, displayText?: string, image?: string, imageAltText?: string, text?: string, title: string, type: string, value?: any }>, "many">, to: z.ZodArray<z.ZodString, "many"> }, "strip", z.ZodTypeAny, { actions: { channelData?: unknown, displayText?: string, image?: string, imageAltText?: string, text?: string, title: string, type: string, value?: any }[], to: string[] }, { actions: { channelData?: unknown, displayText?: string, image?: string, imageAltText?: string, text?: string, title: string, type: string, value?: any }[], to: string[] }>>, summary: z.ZodOptional<z.ZodString>, text: z.ZodOptional<z.ZodString>, textFormat: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["markdown", "plain", "xml"]>, z.ZodString]>>, textHighlights: z.ZodOptional<z.ZodArray<z.ZodObject<{ occurrence: z.ZodNumber, text: z.ZodString }, "strip", z.ZodTypeAny, { occurrence: number, text: string }, { occurrence: number, text: string }>, "many">>, timestamp: z.ZodOptional<z.ZodUnion<[z.ZodDate, z.ZodEffects<z.ZodString, Date, string>]>>, topicName: z.ZodOptional<z.ZodString>, type: z.ZodUnion<[z.ZodEnum<["message", "contactRelationUpdate", "conversationUpdate", "typing", "endOfConversation", "event", "invoke", "invokeResponse", "deleteUserData", "messageUpdate", "messageDelete", "installationUpdate", "messageReaction", "suggestion", "trace", "handoff", "command", "commandResult"]>, z.ZodString]>, value: z.ZodOptional<z.ZodUnknown>, valueType: z.ZodOptional<z.ZodString> }, "strip", z.ZodTypeAny, { action?: string, attachmentLayout?: string, attachments?: { content?: unknown, contentType: string, contentUrl?: string, name?: string, thumbnailUrl?: string }[], callerId?: string, channelData?: any, channelId?: string, code?: string, conversation?: { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, deliveryMode?: string, entities?: z.objectOutputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">[], expiration?: Date, from?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, historyDisclosed?: boolean, id?: string, importance?: string, inputHint?: string, label?: string, listenFor?: string[], localTimestamp?: Date, localTimezone?: string, locale?: string, membersAdded?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }[], membersRemoved?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }[], name?: string, reactionsAdded?: { type: string }[], reactionsRemoved?: { type: string }[], recipient?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, relatesTo?: { activityId?: string, agent?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } | null, channelId: string, conversation: { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, locale?: string, serviceUrl?: string, user?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } }, replyToId?: string, semanticAction?: { entities: Record<string, z.objectOutputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">>, id: string, state: string }, serviceUrl?: string, speak?: string, suggestedActions?: { actions: { channelData?: unknown, displayText?: string, image?: string, imageAltText?: string, text?: string, title: string, type: string, value?: any }[], to: string[] }, summary?: string, text?: string, textFormat?: string, textHighlights?: { occurrence: number, text: string }[], timestamp?: Date, topicName?: string, type: string, value?: unknown, valueType?: string }, { action?: string, attachmentLayout?: string, attachments?: { content?: unknown, contentType: string, contentUrl?: string, name?: string, thumbnailUrl?: string }[], callerId?: string, channelData?: any, channelId?: string, code?: string, conversation?: { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, deliveryMode?: string, entities?: z.objectInputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">[], expiration?: string | Date, from?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, historyDisclosed?: boolean, id?: string, importance?: string, inputHint?: string, label?: string, listenFor?: string[], localTimestamp?: string | Date, localTimezone?: string, locale?: string, membersAdded?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }[], membersRemoved?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }[], name?: string, reactionsAdded?: { type: string }[], reactionsRemoved?: { type: string }[], recipient?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string }, relatesTo?: { activityId?: string, agent?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } | null, channelId: string, conversation: { aadObjectId?: string, conversationType?: string, id: string, isGroup?: boolean, name?: string, properties?: unknown, role?: string, tenantId?: string }, locale?: string, serviceUrl?: string, user?: { aadObjectId?: string, agenticAppBlueprintId?: string, agenticAppId?: string, agenticUserId?: string, id?: string, name?: string, properties?: unknown, role?: string, tenantId?: string } }, replyToId?: string, semanticAction?: { entities: Record<string, z.objectInputType<{ type: z.ZodString }, z.ZodTypeAny, "passthrough">>, id: string, state: string }, serviceUrl?: string, speak?: string, suggestedActions?: { actions: { channelData?: unknown, displayText?: string, image?: string, imageAltText?: string, text?: string, title: string, type: string, value?: any }[], to: string[] }, summary?: string, text?: string, textFormat?: string, textHighlights?: { occurrence: number, text: string }[], timestamp?: string | Date, topicName?: string, type: string, value?: unknown, valueType?: string }>

Type

Zod schema for validating an adaptive card invoke action.

adaptiveCardInvokeActionZodSchema: z.ZodObject<{ data: z.ZodRecord<z.ZodString, z.ZodAny>, id: z.ZodOptional<z.ZodString>, type: z.ZodString, verb: z.ZodString }, "strip", z.ZodTypeAny, { data: Record<string, any>, id?: string, type: string, verb: string }, { data: Record<string, any>, id?: string, type: string, verb: string }>

Type