Add A2A API round-trip support in extract/publish

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

@@ -18,6 +18,7 @@ The kitchen sink APIM instance includes **every resource type and API protocol v
 | `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-a2a-weather-agent` | A2A (JSON-RPC + agent card) | None |
 
 ### Backend Variations
 | Backend | Type |

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

@@ -355,7 +355,7 @@
       ]
     },
     "apis": {
-      "minCount": 9,
+      "minCount": 10,
       "expected": [
         {
           "name": "src-rest-openapi",
@@ -596,6 +596,24 @@
             }
           },
           "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"
+        },
+        {
+          "name": "src-a2a-weather-agent",
+          "files": ["apiInformation.json"],
+          "spotChecks": {
+            "apiInformation.json": {
+              "properties.displayName": "KS A2A Weather Agent",
+              "properties.path": "ks/a2a-weather",
+              "properties.type": "a2a",
+              "properties.agent.id": "src-a2a-weather-agent",
+              "properties.a2aProperties.agentCardPath": "/.well-known/agent.json",
+              "properties.jsonRpcProperties.path": "/",
+              "properties.subscriptionRequired": true,
+              "properties.subscriptionKeyParameterNames.header": "Ocp-Apim-Subscription-Key",
+              "properties.subscriptionKeyParameterNames.query": "subscription-key"
+            }
+          },
+          "notes": "A2A API with JSON-RPC runtime mediation and agent card settings."
         }
       ]
     },

tests/integration/all-resource-types/source-apim.bicep

@@ -901,6 +901,38 @@ resource apiMcpFromExternal 'Microsoft.ApiManagement/service/apis@2025-09-01-pre
   })
 }
 
+// 10. A2A API with JSON-RPC runtime and agent card settings
+// any() used because A2A properties are runtime-supported but may not be present
+// in this API version's Bicep type definitions.
+resource apiA2a 'Microsoft.ApiManagement/service/apis@2025-09-01-preview' = {
+  parent: apim
+  name: 'src-a2a-weather-agent'
+  properties: any({
+    displayName: 'KS A2A Weather Agent'
+    description: 'A2A API exposing JSON-RPC runtime and an APIM-mediated agent card'
+    path: 'ks/a2a-weather'
+    protocols: ['https']
+    type: 'a2a'
+    isAgent: true
+    agent: {
+      id: 'src-a2a-weather-agent'
+    }
+    a2aProperties: {
+      agentCardPath: '/.well-known/agent.json'
+      agentCardBackendUrl: 'https://src-a2a-weather-agent.example.com/.well-known/agent.json'
+    }
+    jsonRpcProperties: {
+      backendUrl: 'https://src-a2a-weather-agent.example.com'
+      path: '/'
+    }
+    subscriptionRequired: true
+    subscriptionKeyParameterNames: {
+      header: 'Ocp-Apim-Subscription-Key'
+      query: 'subscription-key'
+    }
+  })
+}
+
 // ---------------------------------------------------------------------------
 // TIER 3: Child Resources
 // ---------------------------------------------------------------------------

tests/unit/clients/apim-client.test.ts

@@ -1155,6 +1155,13 @@ describe('ApimClient.getApiSpecification', () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 
+  it('should return undefined for a2a apiType without making an HTTP request', async () => {
+    const result = await client.getApiSpecification(testContext, 'a2a-api', 'a2a');
+
+    expect(result).toBeUndefined();
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
   it('should handle top-level link format (api-version 2024-05-01)', async () => {
     // APIM 2024-05-01 returns { link: "..." } at the top level, not nested under value
     const exportResponse = {

tests/unit/services/api-product-extractor.test.ts

@@ -791,6 +791,25 @@ describe('api-extractor', () => {
       expect(getApiSpecification).not.toHaveBeenCalled();
     });
 
+    it('should skip specification export for A2A APIs without calling the client', async () => {
+      const getApiSpecification = vi.fn();
+      const client = createMockClient({
+        getApiSpecification,
+        getResource: vi.fn().mockResolvedValue(undefined),
+      });
+      const store = createMockStore();
+
+      const result = await extractApiResources(
+        client, store, testContext,
+        { type: ResourceType.Api, nameParts: ['a2a-api'] },
+        { name: 'a2a-api', properties: { type: 'a2a' } },
+        '/output'
+      );
+
+      expect(result.specification).toBe(false);
+      expect(getApiSpecification).not.toHaveBeenCalled();
+    });
+
     it('should not call ARM for MCP child resource (data is embedded on the API)', async () => {
       // ARM does not serve apis/{id}/mcpServers/default for MCP APIs; all
       // configuration lives on the API resource itself. The extractor must

tests/unit/services/api-publisher.test.ts

@@ -168,6 +168,36 @@ describe('api-publisher', () => {
       expect(tasks).toHaveLength(2);
     });
 
+    it('should not inject specification import fields for A2A APIs', async () => {
+      const client = createMockClient();
+      const store = createMockStore([]);
+      store.readResource.mockResolvedValue({
+        name: 'a2a-api',
+        properties: {
+          type: 'a2a',
+          path: 'ks/a2a',
+          protocols: ['https'],
+        },
+      });
+      store.readContent.mockResolvedValue({
+        content: 'openapi: "3.0.0"',
+        format: 'yaml',
+      });
+
+      const apiDescriptor: ResourceDescriptor = {
+        type: ResourceType.Api,
+        nameParts: ['a2a-api'],
+      };
+
+      await publishApi(client, store, testContext, apiDescriptor, testConfig);
+
+      const [, , payload] = client.putResource.mock.calls[0] as [unknown, unknown, Record<string, unknown>];
+      const properties = payload.properties as Record<string, unknown>;
+      expect(properties).not.toHaveProperty('format');
+      expect(properties).not.toHaveProperty('value');
+      expect(properties).not.toHaveProperty('apiType');
+    });
+
     it('should return failed result when root API publish fails', async () => {
       const client = createMockClient();
       const store = createMockStore([]);