Table of Contents

Class AgentApplication

Namespace
Microsoft.Agents.Builder.App
Assembly
Microsoft.Agents.Builder.dll

Application class for routing and processing incoming requests.

public class AgentApplication : IAgent
Inheritance
AgentApplication
Implements
Inherited Members

Constructors

AgentApplication(AgentApplicationOptions)

Creates a new AgentApplication instance.

public AgentApplication(AgentApplicationOptions options)

Parameters

options AgentApplicationOptions

Optional. Options used to configure the application.

Properties

AdaptiveCards

Fluent interface for accessing Adaptive Card specific features.

public AdaptiveCardsFeature AdaptiveCards { get; }

Property Value

AdaptiveCardsFeature

Authorization

Accessing user authorization features.

public UserAuthorizationFeature Authorization { get; }

Property Value

UserAuthorizationFeature

Options

The application's configured options.

public AgentApplicationOptions Options { get; }

Property Value

AgentApplicationOptions

Methods

AddRoute(RouteSelector, RouteHandler, bool, ushort)

Adds a new route to the application.

Developers won't typically need to call this method directly as it's used internally by all of the fluent interfaces to register routes for their specific activity types.

Routes will be matched in the order they're added to the application. The first selector to return true when an activity is received will have its handler called.

Invoke-based activities receive special treatment and are matched separately as they typically have shorter execution timeouts.

public AgentApplication AddRoute(RouteSelector selector, RouteHandler handler, bool isInvokeRoute = false, ushort rank = 32767)

Parameters

selector RouteSelector

Function that's used to select a route. The function returning true triggers the route.

handler RouteHandler

Function to call when the route is triggered.

isInvokeRoute bool

Boolean indicating if the RouteSelector is for an activity that uses "invoke" which require special handling. Defaults to false.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnActivity(MultipleRouteSelector, RouteHandler, ushort)

Handles incoming activities of a given type.

public AgentApplication OnActivity(MultipleRouteSelector routeSelectors, RouteHandler handler, ushort rank = 32767)

Parameters

routeSelectors MultipleRouteSelector

Combination of String, Regex, and RouteSelector selectors.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnActivity(RouteSelector, RouteHandler, ushort)

Handles incoming activities of a given type.

public AgentApplication OnActivity(RouteSelector routeSelector, RouteHandler handler, ushort rank = 32767)

Parameters

routeSelector RouteSelector

Function that's used to select a route. The function returning true triggers the route.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnActivity(string, RouteHandler, ushort)

Handles incoming activities of a given type.

public AgentApplication OnActivity(string type, RouteHandler handler, ushort rank = 32767)

Parameters

type string

Name of the activity type to match.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnActivity(Regex, RouteHandler, ushort)

Handles incoming activities of a given type.

public AgentApplication OnActivity(Regex typePattern, RouteHandler handler, ushort rank = 32767)

Parameters

typePattern Regex

Regular expression to match against the incoming activity type.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnAfterTurn(TurnEventHandler)

Add a handler that will execute after the turn's activity handler logic is processed.
Handler returns true to finish execution of the current turn. Handler returning false prevents the Agents state from being saved.

public AgentApplication OnAfterTurn(TurnEventHandler handler)

Parameters

handler TurnEventHandler

Function to call after turn execution.

Returns

AgentApplication

The application instance for chaining purposes.

OnBeforeTurn(TurnEventHandler)

Add a handler that will execute before the turn's activity handler logic is processed.
Handler returns true to continue execution of the current turn. Handler returning false prevents the turn from running, but the Agents state is still saved, which lets you track the reason why the turn was not processed. It also means you can use this as a way to call into the dialog system. For example, you could use the OAuthPrompt to sign the user in before allowing the AI system to run.

public AgentApplication OnBeforeTurn(TurnEventHandler handler)

Parameters

handler TurnEventHandler

Function to call before turn execution.

Returns

AgentApplication

The application instance for chaining purposes.

OnConversationUpdate(RouteSelector, RouteHandler, ushort)

Handles conversation update events using a custom selector.

public virtual AgentApplication OnConversationUpdate(RouteSelector conversationUpdateSelector, RouteHandler handler, ushort rank = 32767)

Parameters

conversationUpdateSelector RouteSelector

This will be used in addition the checking for Activity.Type == ActivityTypes.ConversationUpdate.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnConversationUpdate(string, RouteHandler, ushort)

Handles conversation update events.

public virtual AgentApplication OnConversationUpdate(string conversationUpdateEvent, RouteHandler handler, ushort rank = 32767)

Parameters

conversationUpdateEvent string

Name of the conversation update event to handle, can use ConversationUpdateEvents. If

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnConversationUpdate(string[], RouteHandler, ushort)

Handles conversation update events.

public AgentApplication OnConversationUpdate(string[] conversationUpdateEvents, RouteHandler handler, ushort rank = 32767)

Parameters

conversationUpdateEvents string[]

Name of the conversation update events to handle, can use ConversationUpdateEvents as array item.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnEvent(RouteSelector, RouteHandler, ushort)

Handles incoming Events.

public AgentApplication OnEvent(RouteSelector routeSelector, RouteHandler handler, ushort rank = 32767)

Parameters

routeSelector RouteSelector

Function that's used to select a route. The function returning true triggers the route.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnEvent(string, RouteHandler, ushort)

Handles incoming Event with a specific Name.

public AgentApplication OnEvent(string eventName, RouteHandler handler, ushort rank = 32767)

Parameters

eventName string

Substring of the incoming message text.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnEvent(Regex, RouteHandler, ushort)

Handles incoming Events matching a Name pattern.

public AgentApplication OnEvent(Regex namePattern, RouteHandler handler, ushort rank = 32767)

Parameters

namePattern Regex

Regular expression to match against the text of an incoming message.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnHandoff(HandoffHandler, ushort)

Handles handoff activities.

public AgentApplication OnHandoff(HandoffHandler handler, ushort rank = 32767)

Parameters

handler HandoffHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnMessage(MultipleRouteSelector, RouteHandler, ushort)

Handles incoming messages with a given keyword.
This method provides a simple way to have a Agent respond anytime a user sends a message with a specific word or phrase.

public AgentApplication OnMessage(MultipleRouteSelector routeSelectors, RouteHandler handler, ushort rank = 32767)

Parameters

routeSelectors MultipleRouteSelector

Combination of String, Regex, and RouteSelector selectors.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnMessage(RouteSelector, RouteHandler, ushort)

Handles incoming messages with a given keyword.
This method provides a simple way to have a Agent respond anytime a user sends a message with a specific word or phrase.

public AgentApplication OnMessage(RouteSelector routeSelector, RouteHandler handler, ushort rank = 32767)

Parameters

routeSelector RouteSelector

Function that's used to select a route. The function returning true triggers the route.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnMessage(string, RouteHandler, ushort)

Handles incoming messages with a given keyword.
This method provides a simple way to have an Agent respond anytime a user sends a message with a specific word or phrase.
For example, you can easily clear the current conversation anytime a user sends "/reset":

application.OnMessage("/reset", (context, turnState, _) => ...);
public AgentApplication OnMessage(string text, RouteHandler handler, ushort rank = 32767)

Parameters

text string

Substring of the incoming message text.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnMessage(Regex, RouteHandler, ushort)

Handles incoming messages with a given keyword.
This method provides a simple way to have a Agent respond anytime a user sends a message with a specific word or phrase.
For example, you can easily clear the current conversation anytime a user sends "/reset":

application.OnMessage(new Regex("reset"), (context, turnState, _) => ...);
public AgentApplication OnMessage(Regex textPattern, RouteHandler handler, ushort rank = 32767)

Parameters

textPattern Regex

Regular expression to match against the text of an incoming message.

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnMessageReactionsAdded(RouteHandler, ushort)

Handles message reactions added events.

public AgentApplication OnMessageReactionsAdded(RouteHandler handler, ushort rank = 32767)

Parameters

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnMessageReactionsRemoved(RouteHandler, ushort)

Handles message reactions removed events.

public AgentApplication OnMessageReactionsRemoved(RouteHandler handler, ushort rank = 32767)

Parameters

handler RouteHandler

Function to call when the route is triggered.

rank ushort

0 - ushort.MaxValue for order of evaluation. Ranks of the same value are evaluated in order of addition.

Returns

AgentApplication

The application instance for chaining purposes.

OnTurnAsync(ITurnContext, CancellationToken)

Called by the adapter (for example, a CloudAdapter) at runtime in order to process an inbound Microsoft.Agents.Core.Models.Activity.

public Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)

Parameters

turnContext ITurnContext

The context object for this turn.

cancellationToken CancellationToken

A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

A task that represents the work queued to execute.

OnTurnError(AgentApplicationTurnError)

Allows the AgentApplication to provide error handling without having to change the Adapter.OnTurnError. This is beneficial since the application has more context.

public AgentApplication OnTurnError(AgentApplicationTurnError handler)

Parameters

handler AgentApplicationTurnError

Returns

AgentApplication

Remarks

Exceptions here will bubble-up to Adapter.OnTurnError. Since it isn't know where in the turn the exception was thrown, it is possible that OnAfterTurn handlers, and ITurnState saving has NOT happened.

RegisterExtension<TExtension>(TExtension, Action<TExtension>)

Registers extension with application, providing callback to specify extension features.

public void RegisterExtension<TExtension>(TExtension extension, Action<TExtension> extensionRegistration) where TExtension : IAgentExtension

Parameters

extension TExtension
extensionRegistration Action<TExtension>

Type Parameters

TExtension

StartTypingTimer(ITurnContext)

Manually start a timer to periodically send "typing" activities.

public void StartTypingTimer(ITurnContext turnContext)

Parameters

turnContext ITurnContext

The turn context.

Remarks

The timer waits 1000ms to send its initial "typing" activity and then send an additional "typing" activity every 1000ms.The timer will automatically end once an outgoing activity has been sent. If the timer is already running or the current activity is not a "message" the call is ignored.

StopTypingTimer()

Manually stop the typing timer.

public void StopTypingTimer()

Remarks

If the timer isn't running nothing happens.