Exposing a Microsoft Foundry Agent over A2A via Azure API Management

Connecting enterprise AI capabilities directly to network consumers without unified governance creates security risks, token management sprawl, and architectural debt. Microsoft AI Foundry allows developers to create autonomous AI agents, but directly exposing these endpoints bypassing corporate gateways exposes infrastructure to unthrottled traffic and unmonitored queries.

By placing Azure API Management (APIM) in front of Microsoft AI Foundry’s Agent2Agent (A2A) protocol endpoint, you introduce central governance, subscription key management, consumer quotas, and full OpenTelemetry/Application Insights tracing. When orchestration requirements expand across multiple model providers, developers can also integrate multi-cloud model endpoints alongside custom agents using n1n.ai for unified LLM access.

This step-by-step guide demonstrates how to securely expose a Microsoft AI Foundry agent over the open A2A protocol using APIM and System-Assigned Managed Identity authentication.

Architecture Overview

The sequence flow maps how an unauthenticated network client communicates with the gated APIM instance, which acquires an Entra ID (Azure AD) token on behalf of the caller and proxies the JSON-RPC request to Microsoft AI Foundry.

Postman / Application / Calling Agent
        │
        │  POST https://api.yourcompany.com/agents/helper-agent
        │  Header: Ocp-Apim-Subscription-Key: <key>
        ▼
Azure API Management (APIM)
   ├── 1. Validates Subscription Key & Rate Limits
   ├── 2. Acquires Entra ID Token (Scope: https://ai.azure.com)
   └── 3. Sets Header A2A-Version: 1.0
        │
        ▼  POST https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a
        │  Header: Authorization: Bearer <Entra_Token>
        ▼
Microsoft AI Foundry Agent Endpoint (helper-agent)

Core Technical Benefits

1. Enterprise Governance: Centralized API access controls, rate limiting, and subscription key isolation without altering model backend configurations.
2. Unified Front Door: Single URL path structure (/agents/*) across both AI Foundry native agents and custom-hosted container agents.
3. Zero-Trust Token Exchange: APIM seamlessly exchanges subscription keys for short-lived Entra ID bearer tokens using its System-Assigned Managed Identity.

Prerequisites & Environment Baseline

Ensure the following assets and access levels are available before configuration:

Configuration Reference Values

Replace the placeholders throughout this tutorial with your specific resource values:

• Account Name: contoso-agents-poc
• Project Name: contoso-agents-poc
• Agent Name: helper-agent
• APIM Name: contoso-apim
• Gateway Base Hostname: https://api.yourcompany.com (or https://contoso-apim.azure-api.net)

Target A2A Base Endpoint Format

Every Foundry agent exposes a standardized A2A protocol URI structure:

https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/protocols/a2a

For our target environment, the full base backend URL is: https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a

Step 1: Configure Microsoft AI Foundry Agent & Agent Card

1. Navigate to the Microsoft AI Foundry portal (ai.azure.com). Verify that the New Foundry experience toggle in the top right is active.
2. Select your Project (contoso-agents-poc), navigate to Build → Agents, and click + Create agent.
3. Name the agent helper-agent and attach a deployed chat model (e.g., gpt-4o-mini).
4. Provide operational instructions:

   "You answer questions regarding corporate holiday policies. Be concise. If asked about unrelated subjects, reply that it is outside your scope."

5. Click Save. The agent endpoint is immediately provisioned.

Create the Agent Card (A2A Discovery Metadata)

The Agent Card is a structured JSON manifest defining agent capability scopes for inter-agent discovery.

1. Select helper-agent and navigate to the Details tab.
2. In the A2A / Agent card section, click Create an agent card (Preview).
3. Populate the manifest values:
   • Name: helper-agent
   • Description: Answers corporate holiday policy queries. Excludes payroll and general IT.
   • Topics: holiday, leave, policy, hr
   • Capabilities: Given a query regarding leave, returns structured policy guidance.
   • Sample Prompt: How many days of annual leave are standard?
4. Click Save.

Step 2: Register the A2A API in Azure API Management

1. Open the Azure Portal and select your APIM instance (contoso-apim).
2. From the left menu, select APIs → + Add API.
3. Choose the A2A Agent tile.

Note on Compatibility: Native A2A Agent API import capabilities are available on APIM v2 tiers and classic tiers updated past the mid-2026 release cycle. If absent, manual HTTP API registration can be performed using identical policy blocks.

4. In the URL field, enter the Agent Card Endpoint: https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a/agentCard/v1.0
5. Click Next.

Expected Warning Behavior

APIM will display a notification: "We couldn't retrieve the agent card, possibly due to a wrong url or your network configuration."

This occurs because APIM attempts an unauthenticated GET fetch. Foundry strictly requires an Entra ID bearer token for all endpoints including card reads. Ignore the warning and complete the registration manually:

• Protocol: JSON-RPC
• Runtime URL (JSON-RPC): https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a
• Agent ID: helper-agent
• Display Name: Helper Agent
• Name: helper-agent
• Base path: agents/helper-agent

Click Create.

Step 3: Configure Entra ID RBAC for APIM Managed Identity

APIM must acquire short-lived bearer tokens scoped to https://ai.azure.com to authenticate against Foundry.

Enable System-Assigned Managed Identity

1. In your APIM instance menu, navigate to Security → Managed identities.
2. Select the System assigned tab.
3. Toggle Status to On and click Save. Copy the generated Object (principal) ID.

Assign Azure RBAC Permissions

1. Navigate to the Foundry Project resource in the Azure Portal.
2. Open Access control (IAM) → + Add → Add role assignment.
3. Select the Foundry User role (or assign Foundry Agent Consumer via Azure CLI using Role ID eed3b665-ab3a-47b6-8f48-c9382fb1dad6).
4. Assign access to Managed identity → Select members → Choose your APIM instance contoso-apim.
5. Click Review + assign.

Propagating Delay: Azure RBAC role assignments can take 3 to 5 minutes to propagate across Microsoft Entra ID. Allow this time before issuing test requests to avoid false 401 Unauthorized or 403 Forbidden errors.

Step 4: Define APIM Inbound Policy Rules

Configure the gateway policy to automatically acquire tokens, set target URLs, and inject protocol negotiation headers.

Navigate to APIs → helper-agent → Policies (Code View) and inject the following policy definition:

<policies>
    <inbound>
        <base />
        <authentication-managed-identity resource="https://ai.azure.com" />
        <set-backend-service base-url="https://contoso-agents-poc.services.ai.azure.com/api/projects/contoso-agents-poc/agents/helper-agent/endpoint/protocols/a2a" />
        <set-header name="A2A-Version" exists-action="override">
            <value>1.0</value>
        </set-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Detailed Policy Analysis

• authentication-managed-identity: Requests an Entra ID OAuth access token for resource https://ai.azure.com via the local IMDS identity subsystem and attaches it as a Bearer token to the upstream Authorization header.
• set-backend-service: Explicitly routes traffic to the targeted Foundry agent endpoint, bypassing potential portal settings synchronization mismatches.
• set-header (A2A-Version): Forces protocol version 1.0. Omitting this forces default fallback to version 0.3, which utilizes a legacy message payload structure.

Step 5: Testing End-to-End Routing with Postman

Retrieve an APIM Subscription Key under Subscriptions → Built-in all-access subscription → Show keys.

Request Configuration

• HTTP Method: POST
• URL: https://api.yourcompany.com/agents/helper-agent
• Headers:
  • Ocp-Apim-Subscription-Key: <YOUR_APIM_SUBSCRIPTION_KEY>
  • Content-Type: application/json

Request Payload (A2A v1.0 JSON-RPC 2.0 Specification)

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-001",
      "role": "ROLE_USER",
      "parts": [
        { "text": "What is the policy regarding annual leave allowance?" }
      ]
    }
  }
}

Expected Response (HTTP Status 200 OK)

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "result": {
    "task": {
      "id": "resp_task_99823",
      "contextId": "ctxt_session_4412",
      "status": {
        "state": "TASK_STATE_COMPLETED",
        "timestamp": "2026-09-06T04:18:09+00:00"
      },
      "artifacts": [
        {
          "artifactId": "msg_art_1102",
          "parts": [
            {
              "text": "Employees are entitled to 25 days of paid annual leave per calendar year. Request approval via the HR portal."
            }
          ]
        }
      ]
    }
  }
}

Extract response text from result.task.artifacts[0].parts[0].text. The contextId should be preserved and passed in subsequent requests for stateful multi-turn dialogs.

Troubleshooting & Operational Diagnostics Matrix

Enterprise Integration & Multi-Model Scaling Strategy

While Azure API Management provides governance for native Microsoft AI Foundry agents, modern enterprise architectures often require hybrid LLM integrations. When combining custom A2A agents with third-party foundational models (e.g., Anthropic Claude 3.5 Sonnet, DeepSeek-V3, or OpenAI o3), maintaining separate gateways for each provider increases complexity.

Integrating centralized model routers such as n1n.ai alongside APIM allows organizations to maintain consistent API interfaces across cloud vendors while maintaining tight operational governance over custom agents.

Advanced Pattern: Converting A2A Endpoints to Model Context Protocol (MCP)

To expose A2A-wrapped agents as tools inside Model Context Protocol (MCP) clients:

1. Configure a standard HTTP API in APIM targeting the agent OpenAI-compatible endpoint: .../endpoint/protocols/openai/responses
2. Use APIM's native Expose as MCP server capability to convert API endpoints into schema-compliant MCP tools.

By leveraging structured gateways and robust routing layers like n1n.ai, engineering teams build resilient, scalable agent infrastructures ready for enterprise deployment.

Get a free API key at n1n.ai