Share via

AgentApplication Class

AgentApplication class for routing and processing incoming requests.

The AgentApplication object replaces the traditional ActivityHandler that a bot would use. It supports a simpler fluent style of authoring bots versus the inheritance based approach used by the ActivityHandler class.

Additionally, it has built-in support for calling into the SDK's AI system and can be used to create bots that leverage Large Language Models (LLM) and other AI capabilities.

Constructor

AgentApplication()

Parameters

Name Description
options
Default value: None

Keyword-Only Parameters

Name Description
connection_manager
Default value: None
authorization
Default value: None

Methods

__init__

Creates a new AgentApplication instance.
__new__
activity

Register a new activity event listener as either a decorator or a method.
add_route

Adds a new route to the application.

Routes are ordered by: is_agentic, is_invoke, rank (lower is higher priority), in that order.
conversation_update

Register a handler for conversation update activities as either a decorator or a method.
error

Register an error handler that is invoked whenever the application raises an exception.
handoff

Register a handler to hand off conversations from one copilot to another.
message

Register a new message activity event listener as either a decorator or a method.
message_reaction

Register a handler for message reaction activities as either a decorator or a method.
message_update

Register a handler for message update activities as either a decorator or a method.
on_sign_in_failure

Register a callback that executes when a user fails to sign in.
on_sign_in_success

Register a callback that executes when a user successfully signs in.
on_turn
parse_env_vars_configuration

Parses environment variables and returns a dictionary with the relevant configuration.
turn_state_factory

Custom Turn State Factory

__init__

Creates a new AgentApplication instance.

__init__(options: ApplicationOptions | None = None, *, connection_manager: Connections | None = None, authorization: Authorization | None = None, **kwargs) -> None

Parameters

Name Description
options
Optional[ApplicationOptions]

Configuration options for the application.

Default value: None
connection_manager
Required
Optional[Connections]

OAuth connection manager.
authorization
Required
Optional[Authorization]

Authorization manager for handling authentication flows.
kwargs
Required
Any

Additional configuration parameters.

Keyword-Only Parameters

Name Description
connection_manager
Default value: None
authorization
Default value: None

Returns

Type Description
None

__new__ 

__new__(**kwargs)

activity

Register a new activity event listener as either a decorator or a method.

activity(activity_type: str | ActivityTypes | list[Union[str, ActivityTypes]], *, auth_handlers: list[str] | None = None, **kwargs) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]

Parameters

Name Description
activity_type
Required
Union[str, ActivityTypes, list[Union[str, ActivityTypes]]]

Activity type or collection of types that should trigger the handler.
auth_handlers
Required
Optional[list[str]]

Optional list of authorization handler IDs for the route.
kwargs
Required

Additional route configuration passed to add_route.

Keyword-Only Parameters

Name Description
auth_handlers
Default value: None

Returns

Type Description
Callable[[RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]], RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]]

Examples


   @app.activity("event")
   async def on_event(context: TurnContext, state: TurnState):
       print("hello world!")
       return True

add_route

Adds a new route to the application.

Routes are ordered by: is_agentic, is_invoke, rank (lower is higher priority), in that order.

add_route(selector: Callable[[TurnContext], bool], handler: RouteHandler[StateT], is_invoke: bool = False, is_agentic: bool = False, rank: RouteRank = RouteRank.DEFAULT, auth_handlers: list[str] | None = None) -> None

Parameters

Name Description
selector
Required
Callable[[TurnContext], bool]

A function that takes a TurnContext and returns a boolean indicating whether the route should be selected.
handler
Required

A function that takes a TurnContext and a TurnState and returns an Awaitable.
is_invoke
bool, Optional

Whether the route is for an invoke activity, defaults to False

Default value: False
is_agentic
bool, Optional

Whether the route is for an agentic request, defaults to False. For agentic requests the selector will include a new check for context.activity.is_agentic_request().

Default value: False
rank
<xref:microsoft_agents.hosting.core.app._routes.route_rank.RouteRank>, Optional

The rank of the route, defaults to RouteRank.DEFAULT

Default value: RouteRank.DEFAULT
auth_handlers
Optional[list[str]], Optional

A list of authentication handler IDs to use for this route, defaults to None

Default value: None

Returns

Type Description
None

Exceptions

Type Description
ApplicationError

If the selector or handler are not valid.

conversation_update

Register a handler for conversation update activities as either a decorator or a method.

conversation_update(type: ConversationUpdateTypes, *, auth_handlers: list[str] | None = None, **kwargs) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]

Parameters

Name Description
type
Required
ConversationUpdateTypes

Conversation update category that must match the incoming activity.
auth_handlers
Required
Optional[list[str]]

Optional list of authorization handler IDs for the route.
kwargs
Required

Additional route configuration passed to add_route.

Keyword-Only Parameters

Name Description
auth_handlers
Default value: None

Returns

Type Description
Callable[[RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]], RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]]

Examples


   @app.conversation_update("channelCreated")
   async def on_channel_created(context: TurnContext, state: TurnState):
       print("a new channel was created!")
       return True

error

Register an error handler that is invoked whenever the application raises an exception.

error(func: Callable[[TurnContext, Exception], Awaitable[None]]) -> Callable[[TurnContext, Exception], Awaitable[None]]

Parameters

Name Description
func
Required
Callable[[TurnContext, Exception], Awaitable[None]]

Callable executed when an uncaught exception occurs during a turn.

Returns

Type Description
Callable[[TurnContext, Exception], Awaitable[None]]

Examples


   @app.error
   async def on_error(context: TurnContext, err: Exception):
       print(err)

handoff

Register a handler to hand off conversations from one copilot to another.

handoff(*, auth_handlers: list[str] | None = None, **kwargs) -> Callable[[Callable[[TurnContext, StateT, str], Awaitable[None]]], Callable[[TurnContext, StateT, str], Awaitable[None]]]

Parameters

Name Description
auth_handlers
Required
Optional[list[str]]

Optional list of authorization handler IDs for the route.
kwargs
Required

Additional route configuration passed to add_route.

Keyword-Only Parameters

Name Description
auth_handlers
Default value: None

Returns

Type Description
Callable[[Callable[[TurnContext, <xref:microsoft_agents.hosting.core.app.agent_application.StateT>, str], Awaitable[None]]], Callable[[TurnContext, <xref:microsoft_agents.hosting.core.app.agent_application.StateT>, str], Awaitable[None]]]

Examples


   @app.handoff
   async def on_handoff(context: TurnContext, state: TurnState, continuation: str):
       print(continuation)

message

Register a new message activity event listener as either a decorator or a method.

message(select: str | Pattern[str] | list[Union[str, Pattern[str]]], *, auth_handlers: list[str] | None = None, **kwargs) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]

Parameters

Name Description
select
Required
Union[str, Pattern[str], list[Union[str, Pattern[str]]]]

Literal text, compiled regex, or list of either used to match the incoming message.
auth_handlers
Required
Optional[list[str]]

Optional list of authorization handler IDs for the route.
kwargs
Required

Additional route configuration passed to add_route.

Keyword-Only Parameters

Name Description
auth_handlers
Default value: None

Returns

Type Description
Callable[[RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]], RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]]

Examples


   @app.message("hi")
   async def on_hi_message(context: TurnContext, state: TurnState):
       print("hello!")
       return True

message_reaction

Register a handler for message reaction activities as either a decorator or a method.

message_reaction(type: MessageReactionTypes, *, auth_handlers: list[str] | None = None, **kwargs) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]

Parameters

Name Description
type
Required
MessageReactionTypes

Reaction category that must match the incoming activity.
auth_handlers
Required
Optional[list[str]]

Optional list of authorization handler IDs for the route.
kwargs
Required

Additional route configuration passed to add_route.

Keyword-Only Parameters

Name Description
auth_handlers
Default value: None

Returns

Type Description
Callable[[RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]], RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]]

Examples


   @app.message_reaction("reactionsAdded")
   async def on_reactions_added(context: TurnContext, state: TurnState):
       print("reaction was added!")
       return True

message_update

Register a handler for message update activities as either a decorator or a method.

message_update(type: MessageUpdateTypes, *, auth_handlers: list[str] | None = None, **kwargs) -> Callable[[RouteHandler[StateT]], RouteHandler[StateT]]

Parameters

Name Description
type
Required
MessageUpdateTypes

Message update category that must match the incoming activity.
auth_handlers
Required
Optional[list[str]]

Optional list of authorization handler IDs for the route.
kwargs
Required

Additional route configuration passed to add_route.

Keyword-Only Parameters

Name Description
auth_handlers
Default value: None

Returns

Type Description
Callable[[RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]], RouteHandler[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]]

Examples


   @app.message_update("editMessage")
   async def on_edit_message(context: TurnContext, state: TurnState):
       print("message was edited!")
       return True

on_sign_in_failure

Register a callback that executes when a user fails to sign in.

on_sign_in_failure(func: Callable[[TurnContext, StateT, str | None], Awaitable[None]]) -> Callable[[TurnContext, StateT, str | None], Awaitable[None]]

Parameters

Name Description
func
Required
Callable[[TurnContext, <xref:StateT>, Optional[str]], Awaitable[None]]

Callable that handles the sign-in failure event.

Returns

Type Description
Callable[[TurnContext, <xref:microsoft_agents.hosting.core.app.agent_application.StateT>, str | None], Awaitable[None]]

Exceptions

Type Description
ApplicationError

If authorization services are not configured.

Examples


   @app.on_sign_in_failure
   async def sign_in_failure(context: TurnContext, state: TurnState, connection_id: str | None):
       print("sign-in failed")

on_sign_in_success

Register a callback that executes when a user successfully signs in.

on_sign_in_success(func: Callable[[TurnContext, StateT, str | None], Awaitable[None]]) -> Callable[[TurnContext, StateT, str | None], Awaitable[None]]

Parameters

Name Description
func
Required
Callable[[TurnContext, <xref:StateT>, Optional[str]], Awaitable[None]]

Callable that handles the sign-in success event.

Returns

Type Description
Callable[[TurnContext, <xref:microsoft_agents.hosting.core.app.agent_application.StateT>, str | None], Awaitable[None]]

Exceptions

Type Description
ApplicationError

If authorization services are not configured.

Examples


   @app.on_sign_in_success
   async def sign_in_success(context: TurnContext, state: TurnState, connection_id: str | None):
       print("sign-in succeeded")

on_turn 

async on_turn(context: TurnContext)

Parameters

Name Description
context
Required
TurnContext

parse_env_vars_configuration

Parses environment variables and returns a dictionary with the relevant configuration.

static parse_env_vars_configuration(vars: dict[str, Any]) -> dict

Parameters

Name Description
vars
Required
dict[str, Any]

Dictionary of environment variable names and values.

Returns

Type Description
dict

Parsed configuration dictionary with nested structure.

turn_state_factory

Custom Turn State Factory

turn_state_factory(func: Callable[[TurnContext], Awaitable[StateT]])

Parameters

Name Description
func
Required
Callable[[TurnContext], Awaitable[<xref:microsoft_agents.hosting.core.app.agent_application.StateT>]]

Attributes

adapter

The bot's adapter.

Returns

Type Description
ChannelServiceAdapter

The channel service adapter for the bot.

Exceptions

Type Description
ApplicationError

If the adapter is not configured.

auth

The application's authentication manager

Returns

Type Description
Authorization

The authentication manager for handling OAuth flows.

Exceptions

Type Description
ApplicationError

If authentication is not configured.

options

The application's configured options.

Returns

Type Description
ApplicationOptions

The configuration options for the application.

typing 

typing: TypingIndicator