AI class

Package:

@microsoft/teams-ai

AI System.

Remarks

The AI system is responsible for generating plans, moderating input and output, and generating prompts. It can be used free standing or routed to by the Application object.

Constructors

AI<TState>(AIOptions<TState>)

Creates a new AI system.

Properties

DoCommandActionName	An action that is called to DO an action.
FlaggedInputActionName	An action that will be called anytime an input is flagged by the moderator.
FlaggedOutputActionName	An action that will be called anytime an output is flagged by the moderator.
HttpErrorActionName	An action that will be called anytime the planner encounters an HTTP response with status code >= 400.
moderator	Returns the moderator being used by the AI system.
planner
PlanReadyActionName	An action that will be called after the plan has been predicted by the planner and it has passed moderation.
SayCommandActionName	An action that is called to SAY something.
StopCommandName	A text string that can be returned from an action to stop the AI system from continuing to execute the current plan.
TooManyStepsActionName	The task either executed too many steps or timed out.
UnknownActionName	An action that will be called anytime an unknown action is predicted by the planner.

Methods

action<TParameters>(string | string[], ActionHandler<TState, TParameters>)	Registers a handler for a named action.
defaultAction<TParameters>(string | string[], ActionHandler<TState, TParameters>)	Registers the default handler for a named action.
doAction<TParameters>(TurnContext, TState, string, TParameters)	Manually executes a named action.
hasAction(string)	Checks to see if the AI system has a handler for a given action.
run(TurnContext, TState, number, number)	Calls the configured planner to generate a plan and executes the plan that is returned.

Constructor Details

AI<TState>(AIOptions<TState>)

Creates a new AI system.

new AI(options: AIOptions<TState>)

Parameters

options

AIOptions<TState>

The options used to configure the AI system.

Property Details

DoCommandActionName

An action that is called to DO an action.

static DoCommandActionName: "___DO___" = "___DO___"

Property Value

"DO"

Remarks

The action system is used to do other actions. Overriding this action lets you customize the execution of an individual action. You can use it to log actions being used or to prevent certain actions from being executed based on policy.

The default behavior is to simply execute the action handler passed in so you will need to perform that logic yourself should you override this action.

FlaggedInputActionName

An action that will be called anytime an input is flagged by the moderator.

static FlaggedInputActionName: "___FlaggedInput___" = "___FlaggedInput___"

Property Value

"FlaggedInput"

Remarks

The default behavior is to simply log an error to the console. Override to send a custom message to the user.

FlaggedOutputActionName

An action that will be called anytime an output is flagged by the moderator.

static FlaggedOutputActionName: "___FlaggedOutput___" = "___FlaggedOutput___"

Property Value

"FlaggedOutput"

Remarks

The default behavior is to simply log an error to the console. Override to send a custom message to the user.

HttpErrorActionName

An action that will be called anytime the planner encounters an HTTP response with status code >= 400.

static HttpErrorActionName: "___HttpError___" = "___HttpError___"

Property Value

"HttpError"

moderator

Returns the moderator being used by the AI system.

Moderator<TState> moderator

Property Value

Moderator<TState>

The AI's moderator

planner

Planner<TState> planner

Property Value

Planner<TState>

Returns the planner being used by the AI system.

PlanReadyActionName

An action that will be called after the plan has been predicted by the planner and it has passed moderation.

static PlanReadyActionName: "___PlanReady___" = "___PlanReady___"

Property Value

"PlanReady"

Remarks

Overriding this action lets you customize the decision to execute a plan separately from the moderator. The default behavior is to proceed with the plans execution only with a plan contains one or more commands. Returning false from this action can be used to prevent the plan from being executed.

SayCommandActionName

An action that is called to SAY something.

static SayCommandActionName: "___SAY___" = "___SAY___"

Property Value

"SAY"

Remarks

Overriding this action lets you customize the execution of the SAY command. You can use it to log the output being generated or to add support for sending certain types of output as message attachments.

The default behavior attempts to look for an Adaptive Card in the output and if found sends it as an attachment. If no Adaptive Card is found then the output is sent as a plain text message.

If you override this action and want to automatically send Adaptive Cards as attachments you will need to handle that yourself.

StopCommandName

A text string that can be returned from an action to stop the AI system from continuing to execute the current plan.

static StopCommandName: "STOP" = "STOP"

Property Value

"STOP"

TooManyStepsActionName

The task either executed too many steps or timed out.

static TooManyStepsActionName: "___TooManySteps___" = "___TooManySteps___"

Property Value

"TooManySteps"

UnknownActionName

An action that will be called anytime an unknown action is predicted by the planner.

static UnknownActionName: "___UnknownAction___" = "___UnknownAction___"

Property Value

"UnknownAction"

Remarks

The default behavior is to simply log an error to the console. The plan is allowed to continue execution by default.

Method Details

action<TParameters>(string | string[], ActionHandler<TState, TParameters>)

Registers a handler for a named action.

function action<TParameters>(name: string | string[], handler: ActionHandler<TState, TParameters>): AI<TState>

Parameters

name

string | string[]

Unique name of the action.

handler

ActionHandler<TState, TParameters>

The code to execute when the action's name is triggered.

Returns

AI<TState>

The AI system instance for chaining purposes.

Remarks

The AI systems planner returns plans that are made up of a series of commands or actions that should be performed. Registering a handler lets you provide code that should be run in response to one of the predicted actions.

Plans support a DO command which specifies the name of an action to call and an optional set of entities that should be passed to the action. The internal plan executor will call the registered handler for the action passing in the current context, state, and entities.

Additionally, the AI system itself uses actions to handle things like unknown actions, flagged input, and flagged output. You can override these actions by registering your own handler for them. The names of the built-in actions are available as static properties on the AI class.

defaultAction<TParameters>(string | string[], ActionHandler<TState, TParameters>)

Registers the default handler for a named action.

function defaultAction<TParameters>(name: string | string[], handler: ActionHandler<TState, TParameters>): AI<TState>

Parameters

name

string | string[]

Unique name of the action.

handler

ActionHandler<TState, TParameters>

The code to execute when the action's name is triggered. Default handlers can be replaced by calling the action() method with the same name.

Returns

AI<TState>

The AI system instance for chaining purposes.

doAction<TParameters>(TurnContext, TState, string, TParameters)

Manually executes a named action.

function doAction<TParameters>(context: TurnContext, state: TState, action: string, parameters?: TParameters): Promise<string>

Parameters

context

TurnContext

Current turn context.

state

TState

Current turn state.

action

string

Name of the action to execute.

parameters

TParameters

Optional. Entities to pass to the action.

Returns

Promise<string>

The result of the action.

hasAction(string)

Checks to see if the AI system has a handler for a given action.

function hasAction(action: string): boolean

Parameters

action

string

Name of the action to check.

Returns

boolean

True if the AI system has a handler for the given action.

run(TurnContext, TState, number, number)

Calls the configured planner to generate a plan and executes the plan that is returned.

function run(context: TurnContext, state: TState, start_time?: number, step_count?: number): Promise<boolean>

Parameters

context

TurnContext

Current turn context.

state

TState

Current turn state.

start_time

number

Optional. Time the AI system started running

step_count

number

Optional. Number of steps that have been executed.

Returns

Promise<boolean>

True if the plan was completely executed, otherwise false.

Remarks

The moderator is called to review the input and output of the plan. If the moderator flags the input or output then the appropriate action is called. If the moderator allows the input and output then the plan is executed.