iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use Microsoft Foundry’s REST API to enable incoming A2A, publish a complete agent card, then import that card into an existing Azure API Management (APIM) instance. APIM creates a managed JSON-RPC API, derives or accepts the Foundry runtime URL, and exposes APIM-hosted card and runtime URLs. You can then apply APIM policies and require a subscription key while Foundry continues to enforce Microsoft Entra ID and Foundry role-based access control.
The current workflow is not a portal-only setup: Foundry’s portal does not configure incoming A2A yet. For new integrations, choose A2A v1.0, which is generally available and JSON-RPC-only. The procedure below covers enablement, card discovery, APIM import, authentication, testing, supported modalities, and the failure modes most likely to stop a deployment.
What does exposing a Foundry agent over A2A through APIM actually do?
It places Azure API Management in front of a prompt agent running in Microsoft Foundry Agent Service. Other agents or applications discover the APIM-hosted agent card, then send A2A JSON-RPC requests to the APIM runtime URL. APIM can enforce subscriptions, rate limits, header transformations, logging, and other gateway policies before forwarding the call to Foundry.
Foundry remains the system that authenticates the backend request and authorizes access with Microsoft Entra ID and Foundry RBAC. APIM is the managed edge and policy layer; it does not replace the Foundry role required by the identity making the backend call.
#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.
What do I need before starting?
Collect these items before opening the portal. Missing any one of them usually results in an import or authorization failure.
- An Azure subscription with an active Microsoft Foundry project.
- A deployed prompt agent in Foundry Agent Service and its exact agent name.
- Foundry User or a higher role on the project for the person or automation enabling the feature.
- An existing Azure API Management instance. The A2A import creates an API inside this instance; it does not create the APIM service.
- An agent card in JSON form and the agent’s JSON-RPC runtime URL.
- A Microsoft Entra identity for the caller, APIM managed identity, or another backend identity that has the Foundry Agent Consumer role (or a higher role) for endpoint access.
- Permission to obtain an access token for the
https://ai.azure.comresource.
Use the same Azure region and network assumptions you use for the Foundry project and APIM service. If either service is private, verify that the chosen APIM tier and networking path can reach the Foundry endpoint before troubleshooting protocol details.
How do I enable incoming A2A on the Foundry agent?
Enable the feature with the Foundry REST API or an SDK. The portal can show the project and agent, but it does not currently configure incoming A2A.
1. Identify the project endpoint and agent name
Open the Foundry project and copy its project endpoint. Record the deployed prompt agent’s name exactly as it appears in Agent Service. The name is used in the REST resource path, so capitalization and punctuation matter.
2. Obtain a Microsoft Entra access token
Request a bearer token for the https://ai.azure.com resource with an identity that has Foundry User or a higher project role. Store the token in an environment variable rather than pasting it into shell history or source control.
export FOUNDRY_TOKEN='your-access-token'The token must be valid when the PATCH is sent. A token for a different Azure resource, an expired token, or an identity without project permissions produces an authorization error before A2A settings are evaluated.
3. PATCH the agent with an agent card and protocol configuration
Send a PATCH request to /agents/{agent-name}?api-version=v1. The request must include an agent_card describing the agent and an agent_endpoint.protocol_configuration section that enables both the Responses protocol and A2A.
Recommended Free Tools
curl -X PATCH
"$FOUNDRY_PROJECT_ENDPOINT/agents/$AGENT_NAME?api-version=v1"
-H "Authorization: Bearer $FOUNDRY_TOKEN"
-H "Content-Type: application/json"
--data-raw '{
"agent_card": {
"description": "Answers internal IT operations questions",
"version": "1.0.0",
"skills": [
{
"id": "it-operations",
"name": "IT operations answers",
"description": "Provides text answers about approved IT procedures"
}
]
},
"agent_endpoint": {
"protocol_configuration": {
"responses": {},
"a2a": {}
}
}
}'The property values in the example are illustrative content; use the protocol-configuration shape required by the current Foundry API version and describe the real capabilities of your agent. Do not advertise tools, modalities, or skills that the deployed agent cannot actually provide. A useful card gives clients enough information to select the agent without having to send a trial request.
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.
4. Decide which A2A card version clients should use
Foundry publishes both v1.0 and v0.3 cards under the A2A endpoint. A2A v1.0 is generally available and should be the default for new clients. v0.3 is preview and is appropriate only when an existing client has not yet migrated.
Make the requested version explicit during discovery by using the v1.0 card path, the A2A-Version 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.
How can I verify Foundry before importing anything into APIM?
Verify the native Foundry endpoint first. This separates an A2A configuration problem from an APIM policy or networking problem.
- Fetch the v1.0 agent card with a Microsoft Entra bearer token.
- Check that the card’s description, skills, and
protocolVersiondescribe the intended deployed agent. - Confirm that the card contains a reachable JSON-RPC endpoint and that the endpoint corresponds to the agent you patched.
- Send a basic authenticated request, using a text message supported by the agent.
- Confirm that the calling identity has the Foundry Agent Consumer role or an equivalent higher permission.
Foundry does not provide anonymous card access. A successful card request therefore proves both that the endpoint is configured and that your test identity is authorized. Save the exact card response; you will paste its URL into the APIM import wizard rather than manually rebuilding the card in APIM.
How do I import the A2A agent into Azure API Management?
APIM imports the existing agent card, derives the runtime information when possible, and creates an A2A API with a base path you choose.
1. Open the A2A import wizard
- Sign in to the Azure portal and open your API Management instance.
- In the left menu, select APIs.
- Select + Add API.
- Choose A2A Agent.
2. Supply the Foundry card URL
In Agent card, paste the URL of the verified Foundry v1.0 agent-card JSON and select Next. The APIM service must be able to retrieve this URL. If the Foundry endpoint is private or protected by a network rule, resolve that connectivity issue before retrying the wizard.
3. Review runtime URL and Agent ID
On Create an A2A agent API, inspect the runtime URL and Agent ID. APIM normally infers these values from the card. Supply them explicitly when inference is unavailable or when the card contains a value that is not the runtime endpoint you intend to publish.
4. Set the API metadata and base path
Enter a display name, an optional description, and a unique base path. Keep the path short and stable because clients will use it as part of the APIM runtime URL. Avoid putting secrets, tenant identifiers, or rapidly changing deployment labels in the path.
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.
5. Create the API
Select Create. APIM then shows two important values in the API overview:
- Runtime base URL: the APIM address to which clients send A2A JSON-RPC requests.
- Agent card URL: the APIM-hosted card that clients retrieve for discovery.
Record both values in your integration documentation. Clients should use the APIM card URL, not the original Foundry card URL, when APIM is the public entry point.
What changes does APIM make to the imported agent card?
APIM publishes a gateway-oriented representation rather than copying the Foundry card unchanged.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Card element | APIM behavior | Why it matters |
|---|---|---|
| Hostname | Rewrites the card’s endpoint hostname to the APIM hostname. | Clients discover the gateway address and do not bypass your policies accidentally. |
| Transport preference | Sets JSON-RPC as the preferred transport. | Clients select the transport APIM exposes. |
additionalInterfaces |
Removes other additional interfaces. | The published card does not advertise routes APIM is not managing. |
| Security requirements | Rewrites requirements to include the APIM subscription-key requirement when subscriptions are enabled. | Discovery tells clients how to authenticate at the gateway. |
Review the APIM-hosted card after creation. A card that still points to a direct Foundry hostname, lists an unsupported transport, or omits the expected security requirement should be treated as a configuration problem rather than handed to clients.
How do I secure the runtime and agent card?
Use two authorization layers: APIM subscription controls at the gateway and Microsoft Entra plus Foundry RBAC at the backend.
Require an APIM subscription
- Open the imported API in APIM.
- Open Settings.
- Enable Subscription required.
- Save the API.
Clients can present the subscription key in the Ocp-Apim-Subscription-Key header or as the subscription-key query parameter. Prefer the header so keys do not appear in browser history, proxy logs, or copied URLs.
Keep Foundry authentication on the backend path
The subscription key proves that a caller is allowed through APIM; it does not grant access to the Foundry agent. The identity used for the APIM-to-Foundry call still needs the Foundry Agent Consumer role or a higher role. Depending on your architecture, Foundry documentation describes an agent identity, a project managed identity, delegated user context, OAuth passthrough, and key-based patterns for remote A2A connections.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Choose one identity model deliberately. A project managed identity is easier to operate for a service-to-service integration. Delegated user context is appropriate when the agent must enforce each user’s permissions. Whichever model you choose, grant the narrowest role that permits the required endpoint operation and rotate credentials through your normal Azure identity controls.
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
Where do I add APIM policies for an A2A API?
Open the created API, select A2A, then select Policies. Add XML policies at the A2A API scope for controls that apply only to this agent. Global policies execute before policies at the A2A API scope, so check inherited policies when a request is rejected or transformed unexpectedly.
Common policy categories include:
- Rate limiting to prevent a noisy client from exhausting the agent’s capacity.
- Header insertion or removal for correlation IDs and downstream authentication.
- Request or response transformation when an internal contract differs from the public card.
- Logging and diagnostics routed to your approved monitoring destination.
- IP filtering, quota enforcement, and controlled retry behavior.
Do not log bearer tokens, subscription keys, or complete user prompts when those prompts can contain confidential information. Keep policy transformations compatible with JSON-RPC: changing the request envelope, method, or identifier can cause a protocol error even when the backend is healthy.
How do I test the APIM endpoint end to end?
Test discovery and invocation separately. Discovery confirms the public contract; invocation confirms authentication, policy execution, and backend reachability.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →1. Copy the APIM runtime URL
In the APIM API Overview, copy Runtime base URL. Do not substitute the original Foundry runtime URL in a client intended to use APIM.
2. Send an authenticated JSON-RPC request
Use the method and message shape advertised by the v1.0 card. A typical text request uses the A2A message/send method:
curl -X POST "$APIM_RUNTIME_BASE_URL"
-H "Content-Type: application/json"
-H "Authorization: Bearer $FOUNDRY_ACCESS_TOKEN"
-H "Ocp-Apim-Subscription-Key: $APIM_SUBSCRIPTION_KEY"
--data-raw '{
"jsonrpc": "2.0",
"id": "1",
"method": "message/send",
"params": {
"message": {
"messageId": "test-message-1",
"role": "user",
"parts": [
{ "kind": "text", "text": "Reply with a short health check." }
]
}
}
}'The exact method parameters must match the card and the A2A version selected by the client. If your APIM setup uses a different backend identity, replace the bearer token with the credential that APIM is configured to forward or obtain.
3. Retrieve the APIM agent card
curl -X GET "$APIM_AGENT_CARD_URL"
-H "Ocp-Apim-Subscription-Key: $APIM_SUBSCRIPTION_KEY"Check that the response advertises the APIM hostname, JSON-RPC transport, expected security requirement, protocol version, and the skills you intended to publish. A 401 or 403 at this step usually indicates a missing subscription key or Foundry authorization; a 404 usually indicates an incorrect base path or card URL.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Which A2A features does this integration support?
Design the client around the documented intersection of Foundry incoming A2A and APIM’s A2A API support.
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.
| Capability | Current status for this workflow | Implementation consequence |
|---|---|---|
| A2A v1.0 | Generally available; JSON-RPC-only. | Use it for new integrations and make version selection explicit. |
| A2A v0.3 | Preview. | Retain only for clients that still require the older contract. |
| Text modality | Supported by Foundry incoming A2A. | Use text parts for the supported request and response flow. |
| Responses protocol | Supported when enabled in the agent endpoint configuration. | Keep the Responses configuration alongside A2A during enablement. |
| Server-sent-event streaming | Not supported for Foundry v1.0 incoming A2A. | Clients must handle a non-streaming response. |
| gRPC | Not supported. | Expose JSON-RPC rather than attempting a gRPC transport. |
| HTTP+JSON for v1.0 | Not supported. | Do not configure an HTTP+JSON transport for this endpoint. |
| Nontext modalities | Not supported. | Do not promise image, audio, or other nontext interaction in the card. |
What are the most common failures and fixes?
| Symptom | Likely cause | Fix |
|---|---|---|
| PATCH returns unauthorized | Wrong token audience, expired token, or insufficient Foundry project role. | Request a fresh token for https://ai.azure.com and confirm Foundry User or higher. |
| Card fetch is unauthorized | Anonymous discovery was attempted. | Send a Microsoft Entra bearer token; Foundry card access is not anonymous. |
| Version-ambiguous error | The A2A-Version header and a2a-version query parameter disagree. |
Remove one selector or make both values identical. |
| APIM import cannot read the card | Wrong card URL, private-network reachability issue, or a malformed card. | Fetch the same URL from an authorized client, validate the JSON, and verify APIM-to-Foundry network access. |
| APIM runtime returns 401 or 403 | Missing subscription key or backend identity lacks Foundry Agent Consumer. | Send the APIM key in the header and grant the required Foundry role to the actual calling identity. |
| Runtime returns 404 | Client used the card URL as a runtime URL, or the base path is wrong. | Use the APIM Overview’s Runtime base URL and preserve the configured base path. |
| Client expects streaming | The client assumes a transport that Foundry v1.0 incoming A2A does not support. | Switch to a non-streaming JSON-RPC flow or choose an architecture that supports streaming elsewhere. |
| Card advertises the wrong host or security scheme | Client cached the original Foundry card or APIM settings changed after import. | Retrieve the current APIM Agent card URL and invalidate stale client metadata. |
How should I operate the integration after launch?
Treat the card as a versioned public contract. When skills, descriptions, protocol versions, or authentication requirements change, update the card and test discovery before promoting the change.
- Monitor APIM gateway metrics and backend failures separately so policy rejection is distinguishable from agent failure.
- Set quotas and rate limits according to the agent’s capacity rather than allowing unlimited JSON-RPC calls.
- Keep subscription keys out of source control and rotate them through APIM subscriptions.
- Review Foundry RBAC whenever the backend identity, project, or deployment changes.
- Test both the card URL and runtime URL after every base-path, policy, identity, or network change.
- Document that the public contract is text-only and non-streaming for this Foundry v1.0 path.
When is Foundry Control Plane a better architecture?
If the target is a custom agent that does not run in Foundry Agent Service, Foundry Control Plane can register a reachable custom agent. In that architecture, Foundry uses API Management as a proxy so it can control access and monitor activity. It is an alternative to the direct Agent Service setup described here, not a prerequisite for exposing a deployed Foundry prompt agent.
What should the finished deployment look like?
A correct deployment has an explicitly versioned Foundry card, incoming A2A and Responses enabled, a verified native endpoint, and an APIM API created from that card. Clients discover the APIM-hosted card, present the APIM subscription key when required, and send JSON-RPC text requests to the APIM runtime base URL. The backend identity still passes Foundry’s Entra and RBAC checks, while APIM supplies the gateway controls and operational visibility.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsFrequently Asked Questions
Can one APIM instance expose several Foundry agents?
Yes. Import each agent card as a separate A2A API and give each API a distinct base path. Keep the card, Agent ID, runtime URL, policies, and subscription products aligned per agent so a client cannot accidentally call the wrong deployment.
How can I keep an older A2A client working during a v1.0 migration?
Retain the v0.3 card path only for clients that require it, while publishing v1.0 for new consumers. Make the selected version explicit in discovery and test each client against the corresponding card instead of relying on automatic negotiation.
Should the APIM gateway use a managed identity or delegated user identity?
Use a managed identity for a stable service-to-service trust boundary when every call can use the same agent permissions. Use delegated user context when the agent must apply each end user’s permissions; that design requires an OAuth passthrough or equivalent delegated pattern and more involved token handling.
Can an A2A client call this endpoint with images or audio?
Not on Foundry’s v1.0 incoming A2A path described here. The supported modality is text, so a client requiring nontext input needs a different agent interface or an intermediary that performs an approved conversion before the A2A request.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
