Define an adaptive card within the plugin manifest

[thewahome]

Is your feature request related to a problem? Please describe the problem.

The problem we're trying to solve is the user bringing existing adaptive cards, and wanting to use them in the plugin.

Describe the solution you'd like

Kiota currently must define the adaptive card within the plugin manifest. There are plans to work with TTK to support an external file reference from within the manifest.

Requirements:

• TypeSpec will reference the external AC file.
• Kiota must either:

1. add the adaptive card JSON to plugin manifest
2. reference in the external AC file

Kiota does not support passing AC file on CLI yet. Kiota must handle the path to the AC on the CLI and TypeSpec must pass it.

Additional context

More details have been mentioned in https://github.com/microsoft/typespec-copilot-skills/issues/140

[baywet]

@thewahome since there can be one adaptive card per operation, if we request that information from the user in the CLI, we'll need some mapping syntax like /api/path#GET:/pathtoadaptivecard. We'd require also additional UI in the VSCode extension. While this is not an impossible task, this would require significant additional investments for a "sub-part" experience.
We should probably consider only using an OpenAPI extension at the time which TS would emit based of an annotation and kiota would read.
Thoughts?

[thewahome]

Would the conclusion made earlier still suffice?

• The generated OAD will have the adaptive card in an x-ai extension after Typespec generation
• Kiota should read the adaptive card OAD extension and write it the card in the static template property

[maisarissi]

Kiota should read the adaptive card OAD extension and write it the card in the static template property

I talked to @darrelmiller about that and we discussed that MVL will handle the external file and inline the adaptive card. Kiota should only add the path provided in the OAS extensions as part of the plugin manifest like below:

{
    "functions": [
        {
            "name": "getActiveTasks",
            "description": "Get Active Tasks",
            "capabilities": {
                "response_semantics": {
                    "data_path": "$",
                    "properties": {
                        "title": "$.content",
                        "subtitle": "$.id"
                    },
                    "static_template": {
                        "file": "path_to_the_file"
                    }
                }
            }
        }
    ]
}

[edixon-github]

@maisarissi , @thewahome , where are we on this issue? Is it ready for TypeSpec?

[Onokaev]

@maisarissi , @thewahome , where are we on this issue? Is it ready for TypeSpec?

+1 on this

[sebastienlevert]

The latest versions of TTK now supports externalizing the Adaptive Card. I think we should rely on their work to map it here. @maisarissi, @edixon-github if something is waiting specifically for TypeSpec, we can see from 2 different angles. Either we wait, or we contribute this work to Kiota. If we agree on the design, nothing should be blocking here.

[maisarissi]

For this work, TypeSpec will need to add the link to the external file and the data_path as a OpenAPI extension, so Kiota can get the information and generate the right API plugin with it.

My proposal (as documented in the internal specification) is to add the x-ai-adaptive-card extension:

This extension maps to functions[n].capabilities.response_semantics in the plugin manifest. It provides a data_path that identifies the elements from the response and a path to an external adaptive card file. The extension needs to be added at a function level as each function can have different adaptive cards.

Default: When x-ai-adaptive-card is not defined, the functions[n].capabilities.response_semantics won’t be added.

Example:

{ 
    "paths": { 
        "/emails": { 
           "get": { 
            "operationId": "searchEmails", 
               "description": "search for emails", 
                "x-ai-adaptive-card": { 
                   "data_path": "$.items", 
                   "file": "path_to_file_for_email" 
                },
            "parameters": [ 
                … 
            ] 
                "responses": { 
                    "200": { 
                        "description": "OK" 
                    } 
                } 
            } 
        },
        "/chats": { 
           "get": { 
            "operationId": "searchChats", 
               "description": "search for chats", 
                "x-ai-adaptive-card": { 
                   "data_path": "$.chats", 
                   "file": "path_to_file_for_chat" 
                },
                "responses": { 
                    "200": { 
                        "description": "OK" 
                    } 
                } 
            } 
        }
    } 
} 

This should map to the following API plugin manifest:

{ 
    "functions": [ 
        {
            "name": "searchEmails",
            "description": "search for emails",
            "capabilities": {
                "response_semantics": {
                    "data_path": "$.chats",
                    "static_template": {
                        "file": "path_to_the_file_for_email"
                    } 
                } 
        },
        {
            "name": "searchChats",
            "description": "search for chats",
            "capabilities": {
                "response_semantics": {
                    "data_path": "$.items",
                    "static_template": {
                        "file": "path_to_the_file_for_chat"
                    } 
                } 
            } 
        }
    ] 
}

This work is still pending on Kiota side and I'm working with @petrhollayms and @thewahome to understand the ETA for implementing this and the #6196