Add A2A API round-trip support in extract/publish and all-types integration coverage (#89)

* Add A2A API round-trip support in extract/publish
* Update round-trip test for working mcp server
* Updating round-trip to use real back-ends for demo


---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Elizabeth Maher <enewman@microsoft.com>

Author: Copilot

docs/reference/artifact-format.md

@@ -241,6 +241,7 @@ Example policy XML:
 - **Info file names** follow the pattern `{resourceType}Information.json`
 - **Policy files** are always named `policy.xml`
 - **API specifications** are named `specification.{ext}` (e.g., `specification.yaml`, `specification.json`, `specification.wsdl`)
+  - Specification files are not exported for API types that don't use OpenAPI/WSDL artifacts (for example: WebSocket, MCP, A2A).
 - **Wiki files** are named `wiki.md`
 
 ---

src/clients/apim-client.ts

@@ -586,7 +586,7 @@ export class ApimClient implements IApimClient {
    *   graphql-link          – GraphQL SDL blob        (type=graphql)
    *   wsdl-link             – WSDL blob               (type=soap)
    *   openapi-link          – OpenAPI 3.0 YAML        (type=http, default)
-   *   undefined             –                         (type=websocket — no spec; callers should skip)
+   *   undefined             –                         (type=websocket|a2a — no spec; callers should skip)
    *
    * SOAP APIs use wsdl-link so the exported specification can be re-imported
    * faithfully on publish (matches the Azure/apiops reference tool). APIM's
@@ -612,6 +612,7 @@ export class ApimClient implements IApimClient {
       case 'graphql':   return 'graphql-link';
       case 'soap':      return 'wsdl-link';
       case 'websocket': return undefined;
+      case 'a2a':       return undefined;
       default:          return 'openapi-link';
     }
   }
@@ -743,4 +744,3 @@ export class ApimClient implements IApimClient {
   }
 
 }
-

src/services/api-extractor.ts

@@ -358,6 +358,11 @@ async function extractApiSpecification(
     return false;
   }
 
+  if (apiType?.toLowerCase() === 'a2a') {
+    logger.debug(`Skipping spec export for A2A API "${getNamePart(apiDescriptor.nameParts, 0)}" — A2A APIs use JSON-RPC + agent card endpoints, not OpenAPI`);
+    return false;
+  }
+
   if (apiType?.toLowerCase() === 'graphql' && hasGraphQLSchema(extractedSchemas)) {
     logger.debug(
       `Skipping spec export for synthetic GraphQL API "${getNamePart(apiDescriptor.nameParts, 0)}" — schema is captured via ApiSchema`

src/services/api-publisher.ts

@@ -97,6 +97,11 @@ export async function publishApi(
  * Maps spec file format to APIM ContentFormat for inline import.
  */
 function getImportFormat(specFormat: string, _apiType?: string): string | undefined {
+  const apiType = _apiType?.toLowerCase();
+  if (apiType === 'a2a') {
+    return undefined;
+  }
+
   switch (specFormat) {
     case 'yaml':
       return 'openapi';
@@ -178,7 +183,7 @@ async function publishRootApi(
 
       // The `type` property from GET is read-only and ignored on PUT.
       // APIM uses `apiType` to determine the API kind during spec import.
-      // Always set it explicitly (valid values: http, soap, websocket, graphql, odata, grpc, mcp).
+      // Always set it explicitly (valid values include http, soap, websocket, graphql, odata, grpc, mcp, a2a).
       if (apiType) {
         cleanProps.apiType = apiType;
       }

tests/integration/all-resource-types/README.md

@@ -17,7 +17,8 @@ The kitchen sink APIM instance includes **every resource type and API protocol v
 | `src-rest-versioned-v1` | REST (versioned) | OpenAPI |
 | `src-rest-revisioned` | REST (revisioned) | OpenAPI |
 | `src-mcp-from-api` | MCP (from existing API) | None |
-| `src-mcp-from-external` | MCP (from external MCP server) | None |
+| `src-mcp-existing-server` | MCP (working existing-server demo via Learn) | None |
+| `src-a2a-weather-agent` | A2A (JSON-RPC + agent card) | None |
 
 ### Backend Variations
 | Backend | Type |

tests/integration/all-resource-types/expected-structure.json

@@ -172,17 +172,6 @@
               "properties.pool.services": "exists"
             }
           }
-        },
-        {
-          "name": "src-backend-mcp-external",
-          "files": ["backendInformation.json"],
-          "spotChecks": {
-            "backendInformation.json": {
-              "properties.url": "https://api.githubcopilot.com/mcp",
-              "properties.protocol": "http"
-            }
-          },
-          "notes": "Upstream URL for the MCP-from-external API; the API resource references this backend via backendId"
         }
       ]
     },
@@ -355,7 +344,7 @@
       ]
     },
     "apis": {
-      "minCount": 9,
+      "minCount": 10,
       "expected": [
         {
           "name": "src-rest-openapi",
@@ -579,23 +568,40 @@
           "notes": "MCP API exposing operations of an existing REST API as MCP tools via mcpTools (each tool's operationId references the backing REST API; this MCP API has no operations of its own)"
         },
         {
-          "name": "src-mcp-from-external",
-          "files": ["apiInformation.json", "mcpServerInformation.json"],
+          "name": "src-mcp-existing-server",
+          "files": ["apiInformation.json", "mcpServerInformation.json", "policy.xml"],
           "spotChecks": {
             "apiInformation.json": {
-              "properties.displayName": "KS MCP from External Server",
-              "properties.path": "ks/mcp-external",
+              "properties.displayName": "KS MCP Existing Server Demo",
+              "properties.path": "ks/mcp-existing",
               "properties.type": "mcp",
               "properties.subscriptionRequired": false,
-              "properties.backendId": "src-backend-mcp-external"
+              "properties.backendId": "src-backend-mcp-learn"
             },
             "mcpServerInformation.json": {
-              "properties.mcpProperties": "exists",
               "properties.mcpProperties.endpoints.mcp.uriTemplate": "/mcp",
-              "properties.backendId": "src-backend-mcp-external"
+              "properties.backendId": "src-backend-mcp-learn"
+            }
+          },
+          "notes": "Working existing-server MCP demo. APIM exposes a public Microsoft Learn MCP server through a policy-based MCP proxy so the API is extractable and demoable end to end."
+        },
+        {
+          "name": "src-a2a-weather-agent",
+          "files": ["apiInformation.json"],
+          "spotChecks": {
+            "apiInformation.json": {
+              "properties.displayName": "KS A2A Weather Agent",
+              "properties.path": "ks/a2a-managed",
+              "properties.type": "a2a",
+              "properties.agent.id": "src-a2a-weather-agent",
+              "properties.a2aProperties.agentCardPath": "/.well-known/agent-card.json",
+              "properties.jsonRpcProperties.path": "/ks/a2a-weather",
+              "properties.subscriptionRequired": true,
+              "properties.subscriptionKeyParameterNames.header": "Ocp-Apim-Subscription-Key",
+              "properties.subscriptionKeyParameterNames.query": "subscription-key"
             }
           },
-          "notes": "MCP API repackaging an external MCP server: backendId points to the backend that holds the upstream URL (https://api.githubcopilot.com/mcp), and mcpProperties.endpoints.mcp.uriTemplate addresses the MCP endpoint exposed by that backend"
+          "notes": "A2A API with JSON-RPC runtime mediation and agent card settings."
         }
       ]
     },