Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To expose a Microsoft Foundry Agent Service prompt agent over A2A, first enable incoming A2A on the agent through the Foundry REST API or SDK, publish a complete agent card, verify the JSON-RPC endpoint with Microsoft Entra ID, and then import that card into an existing Azure API Management instance. APIM creates a managed A2A API, publishes its own card and runtime URL, and lets you enforce subscription keys, rate limits, logging, and other policies. This workflow currently supports A2A v1.0, JSON-RPC, text requests, and the Responses protocol; it does not provide streaming, gRPC, HTTP+JSON for v1.0, or nontext modalities.
What do I need before exposing a Foundry agent through APIM?
Prepare the identities, endpoints, and card data before opening the Azure portal. The workflow depends on an already deployed prompt agent and an existing API Management service.
As an Amazon Associate I earn from qualifying purchases.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute- An Azure subscription with an active Microsoft Foundry project.
- A deployed prompt agent in Foundry Agent Service and its agent name.
- Foundry User or a higher role on the project so you can change the agent configuration.
- An existing Azure API Management instance.
- An agent card JSON document describing the agent and its skills.
- The Foundry JSON-RPC runtime URL.
- A calling identity with the Foundry Agent Consumer role, or a higher role, for endpoint access.
- A Microsoft Entra access token for the
https://ai.azure.comresource when you call the Foundry management endpoint.
Incoming A2A is not configured in the Foundry portal at present. Use the documented REST operation or an SDK to enable it, then use the portal for the APIM import and policy work.
Which A2A version should a new integration use?
Use A2A v1.0 for new clients. Microsoft documents v1.0 as generally available, while v0.3 remains a preview intended for clients that still require it.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Foundry can publish both versions of an agent card. Make the desired version explicit during discovery by using the card’s version selector, the A2A-Version HTTP header, or the a2a-version query parameter. Do not send conflicting selectors: if the header and query parameter request different versions, Foundry returns a version-ambiguous error.
What v1.0 means for transport
For this incoming Foundry path, v1.0 is JSON-RPC-only. The supported interaction is text-based and includes the Responses protocol. Server-sent-event streaming, gRPC, HTTP+JSON for v1.0, and nontext modalities are not supported. Choose a different integration pattern when a client requires one of those capabilities.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →How do I enable incoming A2A on the Foundry agent?
Use the project endpoint, the deployed agent name, and an Entra bearer token to patch the agent configuration. The request adds an agent card and declares the Responses and A2A protocol configurations.
1. Identify the project endpoint and agent name
Open the Foundry project details and copy the project endpoint. Record the exact deployed agent name; the name in the URL must match the agent you intend to expose. Keep the endpoint and name available for the verification and APIM steps.
2. Acquire an Entra token
Obtain a Microsoft Entra access token for the https://ai.azure.com audience. The identity obtaining the token must have Foundry User or a higher project role. Store the token securely and send it only over HTTPS.
3. Patch the agent configuration
Send a PATCH request to the agent resource. Replace the values inside the code block with your project endpoint, agent name, token, and real capability descriptions. The card should describe what the agent actually does; client discovery relies on these fields.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
curl -X PATCH "https://YOUR_PROJECT_ENDPOINT/agents/YOUR_AGENT_NAME?api-version=v1"
-H "Authorization: Bearer YOUR_ENTRA_ACCESS_TOKEN"
-H "Content-Type: application/json"
-d '{
"agent_card": {
"description": "Answers internal policy questions from approved documents.",
"version": "1.0.0",
"skills": [
{
"id": "policy-answers",
"name": "Policy answers",
"description": "Returns text answers grounded in approved policy content."
}
]
},
"agent_endpoint": {
"protocol_configuration": {
"responses": {},
"a2a": {}
}
}
}'The endpoint path is /agents/{agent-name}?api-version=v1. Keep the card’s description, version, and skills accurate: APIM imports this document and downstream agents use it to decide whether to call you.
4. Confirm that the patch succeeded
Read the response from the PATCH operation and verify that the agent endpoint now contains the A2A configuration. A successful configuration does not by itself prove that a caller can invoke the runtime; authorization and endpoint reachability still need a separate test.
How do I verify the Foundry card before importing it?
Verify Foundry directly before involving APIM. This separates a Foundry configuration problem from an APIM import or policy problem.
- Request the v1.0 agent-card URL with an Entra bearer token. Use an explicit v1.0 selector so the returned document is unambiguous.
- Check that the description and skills match the agent you intend to publish.
- Check the card’s
protocolVersionand confirm it is the expected v1.0 value. - Confirm that the card’s endpoint is reachable from the network location where APIM will fetch it.
- Verify that the identity used for a runtime call has the Foundry Agent Consumer role or an equivalent higher role.
Foundry does not permit anonymous card access. A request without the required Entra authorization should fail; that is expected and is one reason APIM must be configured with an authenticated backend path.
How do I import the A2A agent into Azure API Management?
APIM imports the existing Foundry card and turns it into a managed A2A API. The portal supplies the card URL, derives the runtime information when possible, and asks you to confirm the public API identity.
- In the Azure portal, open your API Management instance.
- Select APIs in the left navigation.
- Select + Add API.
- Choose A2A Agent.
- In Agent card, paste the URL of the verified Foundry v1.0 agent-card JSON.
- Select Next.
- On Create an A2A agent API, inspect the detected Runtime URL and Agent ID. Supply either value if APIM could not infer it from the card.
- Enter a display name and, if useful for operators, a description.
- Choose a unique base path. This path becomes part of the APIM-hosted runtime URL, so avoid spaces and avoid reusing a path already assigned to another API.
- Select Create.
After creation, the API overview exposes two values you need later: the Runtime base URL for JSON-RPC calls and the APIM Agent card URL for discovery. Save both in your integration notes or deployment configuration.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
What does APIM change when it imports the card?
APIM is not merely storing the original JSON. It mediates the A2A API and publishes a card that describes the APIM-facing service.
- The card hostname is rewritten to the APIM hostname, so clients discover the gateway rather than the underlying Foundry endpoint.
- JSON-RPC is set as the preferred transport.
- Other
additionalInterfacesentries are removed from the APIM-published card. - The security requirements are rewritten to include the APIM subscription-key requirement when subscriptions are enabled.
- APIM creates operations for the JSON-RPC API and routes them to the runtime URL you confirmed during import.
Because the public card can differ from the source card, always fetch the APIM card after creation and inspect what an external client will actually see.
Recommended Free Tools
How do I protect the runtime and card with APIM policies?
Use the A2A API policy scope for gateway controls, while preserving the Microsoft Entra authorization required by Foundry on the backend path.
Configure A2A policies
- Open the newly created API in your APIM instance.
- Select A2A, then Policies.
- Add the XML policies your service requires, such as rate limits, header transformations, request or response handling, and logging.
- Save the policy and test again from the API’s runtime URL.
Global policies run before policies defined at the A2A API scope. Account for that order when a global rule adds, removes, or transforms headers that your A2A policy expects.
Require an APIM subscription
- Open the API’s Settings.
- Enable Subscription required.
- Give each caller an APIM subscription key through the
Ocp-Apim-Subscription-Keyheader, or through thesubscription-keyquery parameter.
With this setting, subscription protection applies to the runtime and to requests for the APIM-published agent card. Treat the card as an API surface: it reveals capabilities and security requirements even though it does not execute the agent.
Keep Foundry authorization in the backend flow
An APIM subscription key is not a replacement for Foundry authorization. The caller, APIM managed identity, or another configured identity must still satisfy Foundry’s role checks. Foundry documents several patterns for remote A2A connections, including an agent identity, a project managed identity, delegated user context, OAuth passthrough, and key-based approaches. Select the pattern that matches your trust boundary and ensure the resulting identity has the required Foundry role.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
How do I test the APIM runtime and agent card?
Test discovery and invocation separately. A card can be reachable while the runtime authorization is wrong, or the reverse.
1. Copy the runtime URL
From the APIM API’s Overview page, copy the Runtime base URL. Use the APIM URL, not the original Foundry runtime URL, for the external call.
2. Send a JSON-RPC request
POST a JSON-RPC request to the runtime base URL. Include the APIM subscription header if you enabled subscriptions and include the authentication required by the Foundry backend. The method and parameters must match the operation advertised by the card and supported by your agent.
POST https://YOUR_APIM_HOST/YOUR_BASE_PATH
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY
Authorization: Bearer YOUR_BACKEND_ACCESS_TOKEN
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": "request-1",
"method": "METHOD_ADVERTISED_BY_THE_AGENT_CARD",
"params": {
"input": "Summarize the approved policy text."
}
}The response should be a JSON-RPC result or error from the mediated operation. If APIM returns an authentication or subscription error before the request reaches Foundry, fix the gateway credentials first; if Foundry returns a role error, fix the backend identity assignment.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
3. Fetch and inspect the APIM card
GET the APIM Agent card URL, adding the subscription key when required. Confirm that the returned card advertises the APIM hostname, JSON-RPC as the transport, the expected security requirement, and the skills you published for the agent. This is the document external agents will use for discovery.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What commonly fails, and how do I fix it?
- The Foundry portal has no A2A setting: use the REST PATCH operation or an SDK. The portal does not currently configure incoming A2A.
- Card discovery returns an authorization error: send a valid Entra token and verify that the identity can read the Foundry project and agent. Anonymous card requests are not supported.
- Foundry reports an ambiguous A2A version: remove the disagreement between the
A2A-Versionheader anda2a-versionquery parameter, or use only one explicit selector. - APIM cannot determine the runtime URL or Agent ID: return to the import wizard’s Create an A2A agent API page and enter both values manually after checking the source card.
- The APIM card shows the wrong host: fetch the card from the APIM card URL, not the Foundry URL. APIM intentionally rewrites the hostname for the public representation.
- A request is rejected before reaching Foundry: check the APIM subscription header, base path, global policies, and A2A API policies.
- Foundry rejects an otherwise valid gateway request: check the backend token, managed identity or OAuth passthrough configuration, and the Foundry Agent Consumer role.
- A streaming or nontext client fails: this incoming Foundry A2A implementation does not support server-sent events, gRPC, HTTP+JSON for v1.0, or nontext modalities. Use a protocol and architecture that supports the required modality.
When is a different architecture better?
APIM import is appropriate when the target is a Foundry Agent Service prompt agent that already exposes a JSON-RPC A2A card. It is not a universal adapter for every agent protocol.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
For custom agents that are reachable outside Agent Service, Foundry Control Plane can register the agent and use API Management as a proxy for access control and monitoring. That route is an alternative architecture rather than an extra step in the Agent Service import flow. Evaluate it when your agent is not hosted as a Foundry prompt agent or when you need the custom-agent registration model.
Production checklist for the completed integration
- The Foundry agent has an accurate description, version, and skills list.
- Incoming A2A is enabled through the REST API or SDK.
- Clients are directed to the v1.0 card unless a specific consumer still requires v0.3.
- Card discovery is tested with an Entra token and an explicit, nonconflicting version selector.
- The APIM import uses the verified v1.0 card URL.
- The runtime URL, Agent ID, display name, and base path are correct.
- APIM policies are saved at the intended scope, with global-policy ordering understood.
- Subscription protection is enabled when gateway-level caller control is required.
- The backend identity retains the Foundry Agent Consumer role or a higher role.
- Both the APIM card URL and runtime base URL have been tested independently.
- Clients are told that the supported interaction is text JSON-RPC and that streaming and nontext requests are unavailable.
Frequently Asked Questions
Can I let an unauthenticated client download the Foundry agent card?
No. Foundry requires Entra authorization for card access. If you publish the card through APIM, apply the API’s subscription requirement consistently and document the key requirement for discovery clients.
Free tools Windows power users keep installed
One-click scans. No signup required.
How can I migrate consumers from A2A v0.3 to v1.0?
Keep the v0.3 card available only for clients that still depend on it, while directing new integrations to the v1.0 card. During migration, make every client choose its version explicitly so a stale header or query parameter cannot create an ambiguous request.
Should the caller or APIM hold the Foundry Agent Consumer role?
That depends on your trust model. Foundry supports an agent identity, project managed identity, delegated user context, OAuth passthrough, and key-based patterns; whichever identity actually reaches the Foundry runtime must have the required role.
What should an external agent cache from the APIM card?
Cache the APIM-published hostname, JSON-RPC transport information, security requirement, and skills, then refresh it according to your client’s discovery policy. Do not substitute the original Foundry card, because APIM intentionally rewrites the public representation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
