AgentApplication.AdaptiveCard support

changelog.md

@@ -3,9 +3,10 @@
 ## Major Features & Enhancements
 - Added support for Workload Identity
 - **Entra JWT Issuer Validation**: Added tenant ID cross-checking for Entra issuer claims and support for configuring issuer lists through environment variables (#515)
+- **AgentApplication Adaptive Card Routing**: Added `AgentApplication.adaptive_card` with decorator-based handlers for Adaptive Card `Action.Submit`, `Action.Execute`, and `Data.Query` dynamic search with verb and dataset matching selection.
 
 ## New Models & APIs
-- **Regionalized UserTokenClient Support**: Added optional argument to `CloudAdapter` to configure Token Service endpoint used by `RestChannelServiceClientFactory` when creating `UserTokenClient` instances. 
+- **Regionalized UserTokenClient Support**: Added optional argument to `CloudAdapter` to configure Token Service endpoint used by `RestChannelServiceClientFactory` when creating `UserTokenClient` instances.
 
 ## Bug Fixes
 - **OAuth Flow Storage**: Avoided redundant writes when the flow state is unchanged in the cache.

libraries/microsoft-agents-activity/microsoft_agents/activity/__init__.py

@@ -10,6 +10,7 @@
 from .adaptive_card_invoke_action import AdaptiveCardInvokeAction
 from .adaptive_card_invoke_response import AdaptiveCardInvokeResponse
 from .adaptive_card_invoke_value import AdaptiveCardInvokeValue
+from .adaptive_card_search_invoke_value import AdaptiveCardSearchInvokeValue
 from .animation_card import AnimationCard
 from .attachment import Attachment
 from .attachment_data import AttachmentData
@@ -66,6 +67,8 @@
 from .receipt_item import ReceiptItem
 from .resource_response import ResourceResponse
 from .semantic_action import SemanticAction
+from .search_invoke_options import SearchInvokeOptions
+from .search_invoke_value import SearchInvokeValue
 from .signin_card import SigninCard
 from .suggested_actions import SuggestedActions
 from .text_highlight import TextHighlight
@@ -117,6 +120,7 @@
     "AdaptiveCardInvokeAction",
     "AdaptiveCardInvokeResponse",
     "AdaptiveCardInvokeValue",
+    "AdaptiveCardSearchInvokeValue",
     "AnimationCard",
     "Attachment",
     "AttachmentData",
@@ -167,6 +171,8 @@
     "ReceiptCard",
     "ReceiptItem",
     "ResourceResponse",
+    "SearchInvokeOptions",
+    "SearchInvokeValue",
     "SemanticAction",
     "SigninCard",
     "SuggestedActions",

libraries/microsoft-agents-activity/microsoft_agents/activity/adaptive_card_invoke_action.py

@@ -1,6 +1,8 @@
 # Copyright (c) Microsoft Corporation. All rights reserved.
 # Licensed under the MIT License.
 
+from pydantic import Field
+
 from .agents_model import AgentsModel
 from ._type_aliases import NonEmptyString
 
@@ -14,14 +16,14 @@ class AdaptiveCardInvokeAction(AgentsModel):
     :param type: The Type of this Adaptive Card Invoke Action.
     :type type: str
     :param id: The Id of this Adaptive Card Invoke Action.
-    :type id: str
+    :type id: str | None
     :param verb: The Verb of this Adaptive Card Invoke Action.
-    :type verb: str
+    :type verb: str | None
     :param data: The data of this Adaptive Card Invoke Action.
     :type data: dict[str, object]
     """
 
-    type: NonEmptyString = None
-    id: NonEmptyString = None
-    verb: NonEmptyString = None
-    data: dict[NonEmptyString, object] = None
+    type: str
+    id: str | None = None
+    verb: str | None = None
+    data: dict[NonEmptyString, object] = Field(default_factory=dict)

libraries/microsoft-agents-activity/microsoft_agents/activity/adaptive_card_invoke_response.py

@@ -14,10 +14,10 @@ class AdaptiveCardInvokeResponse(AgentsModel):
     :type status_code: int
     :param type: The type of this Card Action Response.
     :type type: str
-    :param value: The JSON response object.
-    :type value: dict[str, object]
+    :param value: The response object.
+    :type value: object
     """
 
     status_code: int = None
     type: NonEmptyString = None
-    value: dict[NonEmptyString, object] = None
+    value: object = None

libraries/microsoft-agents-activity/microsoft_agents/activity/adaptive_card_invoke_value.py

@@ -20,6 +20,6 @@ class AdaptiveCardInvokeValue(AgentsModel):
     :type state: str
     """
 
-    action: AdaptiveCardInvokeAction = None
-    authentication: TokenExchangeInvokeRequest = None
+    action: AdaptiveCardInvokeAction
+    authentication: TokenExchangeInvokeRequest | None = None
     state: NonEmptyString = None

libraries/microsoft-agents-activity/microsoft_agents/activity/adaptive_card_search_invoke_value.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .search_invoke_value import SearchInvokeValue
+
+
+class AdaptiveCardSearchInvokeValue(SearchInvokeValue):
+    """
+    :param dataset: The dataset for this adaptive card search value.
+    :type dataset: str
+    """
+
+    dataset: str | None = None

libraries/microsoft-agents-activity/microsoft_agents/activity/content_types.py

@@ -10,7 +10,13 @@ class ContentTypes:
     audio_card = "application/vnd.microsoft.card.audio"
     hero_card = "application/vnd.microsoft.card.hero"
     receipt_card = "application/vnd.microsoft.card.receipt"
+    error = "application/vnd.microsoft.error"
     oauth_card = "application/vnd.microsoft.card.oauth"
     signin_card = "application/vnd.microsoft.card.signin"
     thumbnail_card = "application/vnd.microsoft.card.thumbnail"
     video_card = "application/vnd.microsoft.card.video"
+    message = "application/vnd.microsoft.activity.message"
+    login_request = "application/vnd.microsoft.activity.loginRequest"
+    incorrect_auth_code = "application/vnd.microsoft.error.incorrectAuthCode"
+    precondition_failed = "application/vnd.microsoft.error.preconditionFailed"
+    search_response = "application/vnd.microsoft.search.searchResponse"

libraries/microsoft-agents-activity/microsoft_agents/activity/search_invoke_options.py

@@ -0,0 +1,17 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .agents_model import AgentsModel
+
+
+class SearchInvokeOptions(AgentsModel):
+    """Defines the query options in the 'SearchInvokeValue' for Invoke activity with name of 'application/search'.
+
+    :param skip: The number of items to skip in the search results. This is an integer that specifies how many items to skip in the search results.
+    :type skip: int
+    :param top: The maximum number of items to return in the search results. This is an integer that specifies the maximum number of items to return in the search results.
+    :type top: int
+    """
+
+    skip: int
+    top: int

libraries/microsoft-agents-activity/microsoft_agents/activity/search_invoke_value.py

@@ -0,0 +1,21 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .agents_model import AgentsModel
+from .search_invoke_options import SearchInvokeOptions
+
+
+class SearchInvokeValue(AgentsModel):
+    """Defines the structure that arrives in Activity.value for invoke activity with name of 'application/search'.
+
+    :param kind: The kind of search being performed. This is a string that is used to identify the type of search being performed.
+    :type kind: str
+    :param query_text: The text of the search query. This is a string that contains the text of the search query being performed.
+    :type query_text: str
+    :param query_options: The options for the search query. This is an object that contains the options for the search query being performed.
+    :type query_options: :class:`microsoft_agents.activity.search_invoke_options.SearchInvokeOptions`
+    """
+
+    kind: str
+    query_text: str
+    query_options: SearchInvokeOptions

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/adaptive_card/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from .adaptive_card import AdaptiveCard
+
+__all__ = ["AdaptiveCard"]

libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/app/adaptive_card/_type_defs.py

@@ -0,0 +1,46 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from typing import Awaitable, Protocol
+
+from microsoft_agents.activity import (
+    AdaptiveCardInvokeResponse,
+    AdaptiveCardInvokeValue,
+)
+
+from microsoft_agents.hosting.core.turn_context import TurnContext
+from microsoft_agents.hosting.core.app.state import TurnState
+
+from .models import (
+    AdaptiveCardSearchParams,
+    AdaptiveCardSearchResult,
+    Query,
+)
+
+
+class ActionExecuteHandler(Protocol):
+    def __call__(
+        self, context: TurnContext, state: TurnState, data: object, /
+    ) -> Awaitable[AdaptiveCardInvokeResponse]: ...
+
+
+class ActionExecuteValueHandler(Protocol):
+    def __call__(
+        self, context: TurnContext, state: TurnState, value: AdaptiveCardInvokeValue, /
+    ) -> Awaitable[AdaptiveCardInvokeResponse]: ...
+
+
+class ActionSubmitHandler(Protocol):
+    def __call__(
+        self, context: TurnContext, state: TurnState, data: object, /
+    ) -> Awaitable[None]: ...
+
+
+class SearchHandler(Protocol):
+    def __call__(
+        self,
+        context: TurnContext,
+        state: TurnState,
+        query: Query[AdaptiveCardSearchParams],
+        /,
+    ) -> Awaitable[list[AdaptiveCardSearchResult]]: ...