Class AgentApplication
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
AgentApplicationOptionsOptional. Options used to configure the application.
Properties
AdaptiveCards
Fluent interface for accessing Adaptive Card specific features.
public AdaptiveCardsFeature AdaptiveCards { get; }
Property Value
Authorization
Accessing user authorization features.
public UserAuthorizationFeature Authorization { get; }
Property Value
Options
The application's configured options.
public AgentApplicationOptions Options { get; }
Property Value
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
RouteSelectorFunction that's used to select a route. The function returning true triggers the route.
handler
RouteHandlerFunction to call when the route is triggered.
isInvokeRoute
boolBoolean indicating if the RouteSelector is for an activity that uses "invoke" which require special handling. Defaults to
false
.rank
ushort0 - 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
MultipleRouteSelectorCombination of String, Regex, and RouteSelector selectors.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RouteSelectorFunction that's used to select a route. The function returning true triggers the route.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
stringName of the activity type to match.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RegexRegular expression to match against the incoming activity type.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
TurnEventHandlerFunction 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
TurnEventHandlerFunction 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
RouteSelectorThis will be used in addition the checking for Activity.Type == ActivityTypes.ConversationUpdate.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
stringName of the conversation update event to handle, can use ConversationUpdateEvents. If
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RouteSelectorFunction that's used to select a route. The function returning true triggers the route.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
stringSubstring of the incoming message text.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RegexRegular expression to match against the text of an incoming message.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
HandoffHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
MultipleRouteSelectorCombination of String, Regex, and RouteSelector selectors.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RouteSelectorFunction that's used to select a route. The function returning true triggers the route.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
stringSubstring of the incoming message text.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RegexRegular expression to match against the text of an incoming message.
handler
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
RouteHandlerFunction to call when the route is triggered.
rank
ushort0 - 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
ITurnContextThe context object for this turn.
cancellationToken
CancellationTokenA 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
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
TExtensionextensionRegistration
Action<TExtension>
Type Parameters
TExtension
StartTypingTimer(ITurnContext)
Manually start a timer to periodically send "typing" activities.
public void StartTypingTimer(ITurnContext turnContext)
Parameters
turnContext
ITurnContextThe 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.