AgentApplication class

Example

const app = new AgentApplication({
  storage: new MemoryStorage(),
  adapter: myAdapter,
  startTypingTimer: true,
  authorization: { connectionName: 'oauth' },
  transcriptLogger: myTranscriptLogger,
});

new AgentApplication(options?: Partial<AgentApplicationOptions<TState>>)

Parameters

Remarks

The constructor initializes the application with default settings and applies any provided options. It sets up the adapter, authorization, and other core components based on the configuration.

Default options:

• startTypingTimer: false
• longRunningMessages: false
• removeRecipientMention: true
• turnStateFactory: Creates a new TurnState instance

BaseAdapter adapter

Property Value

The adapter instance.

Example

app.adaptiveCards.actionSubmit('doStuff', async (context, state, data) => {
  await context.sendActivity(`Received data: ${JSON.stringify(data)}`);
});

AdaptiveCardsActions<TState> adaptiveCards

Property Value

The adaptive cards actions instance.

Authorization authorization

Property Value

The authorization instance.

AgentApplicationOptions<TState> options

Property Value

The application options.

Adds a new route to the application for handling activities.

Example

app.addRoute(
  async (context) => context.activity.type === ActivityTypes.Message,
  async (context, state) => {
    await context.sendActivity('I received your message');
  },
  false, // isInvokeRoute
  RouteRank.First // rank
);

function addRoute(selector: Selector, handler: RouteHandler<TState>, isInvokeRoute?: boolean, rank?: number, authHandlers?: string[]): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

Routes are evaluated by rank order (if provided), otherwise, in the order they are added. Invoke-based activities receive special treatment and are matched separately as they typically have shorter execution timeouts.

Adds a handler for specific activity types.

Example

app.onActivity(ActivityTypes.Message, async (context, state) => {
  await context.sendActivity('I received your message');
});

function onActivity(type: string | RegExp | Selector | (string | RegExp | Selector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[], rank?: RouteRank): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method allows you to register handlers for specific activity types such as 'message', 'conversationUpdate', etc. You can specify multiple activity types by passing an array.

Adds a handler for conversation update events.

Example

app.onConversationUpdate('membersAdded', async (context, state) => {
  const membersAdded = context.activity.membersAdded;
  for (const member of membersAdded) {
    if (member.id !== context.activity.recipient.id) {
      await context.sendActivity('Hello and welcome!');
    }
  }
});

function onConversationUpdate(event: ConversationUpdateEvents, handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[], rank?: RouteRank): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

Conversation update events occur when the state of a conversation changes, such as when members join or leave.

Sets an error handler for the application.

Example

app.onError(async (context, error) => {
  console.error(`An error occurred: ${error.message}`);
  await context.sendActivity('Sorry, something went wrong!');
});

function onError(handler: (context: TurnContext, error: Error) => Promise<void>): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method allows you to handle any errors that occur during turn processing. The handler will receive the turn context and the error that occurred.

Adds a handler for message activities that match the specified keyword or pattern.

Example

app.onMessage('hello', async (context, state) => {
  await context.sendActivity('Hello there!');
});

app.onMessage(/help/i, async (context, state) => {
  await context.sendActivity('How can I help you?');
});

function onMessage(keyword: string | RegExp | Selector | (string | RegExp | Selector)[], handler: (context: TurnContext, state: TState) => Promise<void>, authHandlers?: string[], rank?: RouteRank): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method allows you to register handlers for specific message patterns. If keyword is a string, it matches messages containing that string. If keyword is a RegExp, it tests the message text against the regular expression. If keyword is a function, it calls the function with the context to determine if the message matches.

Adds a handler for message reaction added events.

Example

app.onMessageReactionAdded(async (context, state) => {
  const reactionsAdded = context.activity.reactionsAdded;
  if (reactionsAdded && reactionsAdded.length > 0) {
    await context.sendActivity(`Thanks for your ${reactionsAdded[0].type} reaction!`);
  }
});

function onMessageReactionAdded(handler: (context: TurnContext, state: TState) => Promise<void>, rank?: RouteRank): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method registers a handler that will be invoked when a user adds a reaction to a message, such as a like, heart, or other emoji reaction.

Adds a handler for message reaction removed events.

Example

app.onMessageReactionRemoved(async (context, state) => {
  const reactionsRemoved = context.activity.reactionsRemoved;
  if (reactionsRemoved && reactionsRemoved.length > 0) {
    await context.sendActivity(`You removed your ${reactionsRemoved[0].type} reaction.`);
  }
});

function onMessageReactionRemoved(handler: (context: TurnContext, state: TState) => Promise<void>, rank?: RouteRank): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method registers a handler that will be invoked when a user removes a reaction from a message, such as unliking or removing an emoji reaction.

Sets a handler to be called when a sign-in attempt fails.

Example

app.onSignInFailure(async (context, state) => {
  await context.sendActivity('Sign-in failed. Please try again.');
});

function onSignInFailure(handler: (context: TurnContext, state: TurnState<DefaultConversationState, DefaultUserState, DefaultTempState>, id?: string) => Promise<void>): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method allows you to handle cases where a user fails to authenticate, such as when they cancel the sign-in process or an error occurs.

Sets a handler to be called when a user successfully signs in.

Example

app.onSignInSuccess(async (context, state) => {
  await context.sendActivity('You have successfully signed in!');
});

function onSignInSuccess(handler: (context: TurnContext, state: TurnState<DefaultConversationState, DefaultUserState, DefaultTempState>, id?: string) => Promise<void>): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

This method allows you to perform actions after a user has successfully authenticated. The handler will receive the turn context and state.

Adds an event handler for specified turn events.

Example

app.onTurn('beforeTurn', async (context, state) => {
  console.log('Processing before turn');
  return true; // Continue execution
});

function onTurn(event: TurnEvents | TurnEvents[], handler: (context: TurnContext, state: TState) => Promise<boolean>): AgentApplication<TState>

Parameters

Returns

The current instance of the application.

Remarks

Turn events allow you to execute logic before or after the main turn processing. Handlers added for 'beforeTurn' are executed before routing logic. Handlers added for 'afterTurn' are executed after routing logic.

Registers an extension with the application.

Example

const myExtension = new MyCustomExtension();
app.registerExtension(myExtension, (ext) => {
  console.log('Extension registered:', ext.name);
});

function registerExtension<T>(extension: T, regcb: (ext: T) => void)

Parameters

Remarks

Extensions provide a way to add custom functionality to the application. Each extension can only be registered once to prevent conflicts.

Executes the application logic for a given turn context.

Example

const app = new AgentApplication();
await app.run(turnContext);

function run(turnContext: TurnContext): Promise<void>

Parameters

Returns

A promise that resolves when the application logic has completed.

Remarks

This method is the entry point for processing a turn in the conversation. It delegates the actual processing to the runInternal method, which handles the core logic for routing and executing handlers.

Executes the application logic for a given turn context.

Example

const handled = await app.runInternal(turnContext);
if (!handled) {
  console.log('No handler matched the activity');
}

function runInternal(turnContext: TurnContext): Promise<boolean>

Parameters

Returns

A promise that resolves to true if a handler was executed, false otherwise.

Remarks

This is the core internal method that processes a turn in the conversation. It handles routing and executing handlers based on the activity type and content. While this method is public, it's typically called internally by the run method.

The method performs the following operations:

1. Starts typing timer if configured
2. Processes mentions if configured
3. Loads turn state
4. Handles authentication flows
5. Executes before-turn event handlers
6. Downloads files if file downloaders are configured
7. Routes to appropriate handlers
8. Executes after-turn event handlers
9. Saves turn state

Sends a proactive message to a conversation.

Example

// With conversation reference
await app.sendProactiveActivity(conversationReference, 'Important notification!');

// From an existing context
await app.sendProactiveActivity(turnContext, 'Important notification!');

function sendProactiveActivity(context: TurnContext | ConversationReference, activityOrText: string | Activity, speak?: string, inputHint?: string): Promise<undefined | ResourceResponse>

Parameters

Returns

A promise that resolves to the resource response from sending the activity.

Remarks

This method allows you to send messages proactively to a conversation, outside the normal turn flow.

Starts a typing indicator timer for the current turn context.

Example

app.startTypingTimer(turnContext);
// Do some processing...
await turnContext.sendActivity('Response after processing');
// Typing timer automatically stops when sending a message

function startTypingTimer(context: TurnContext)

Parameters

Remarks

This method starts a timer that sends typing activity indicators to the user at regular intervals. The typing indicator continues until a message is sent or the timer is explicitly stopped.

The typing indicator helps provide feedback to users that the agent is processing their message, especially when responses might take time to generate.

Stops the typing indicator timer if it's currently running.

Example

app.startTypingTimer(turnContext);
// Do some processing...
app.stopTypingTimer(); // Manually stop the typing indicator

function stopTypingTimer()

Remarks

This method clears the typing indicator timer to prevent further typing indicators from being sent. It's typically called automatically when a message is sent, but can also be called manually to stop the typing indicator.