Last verified: September 2026. Foundry's incoming-A2A endpoint is still in public preview; APIM's A2A agent API support is GA.
A Foundry agent that any authorised client on your network can call through your API gateway, using the open Agent2Agent (A2A) protocol, like this:
You'll finish when you send a JSON-RPC message from Postman and get the agent's answer back. Nothing more. Wiring a second agent to call the first, or turning agents into MCP tools, are follow-on articles.
Foundry agents already have an endpoint. Two reasons to put APIM in front: Governance. Subscription keys, per-consumer quotas, content-safety policies, App Insights traces — all in one place you already operate. When Security asks "who can call this agent and how often?", the answer is an APIM product, not a wiki page. One front door for everything. The same URL pattern works for Foundry agents today and for agents hosted anywhere else (Container Apps, other clouds) tomorrow.
| Thing | Why | |---|---| | A Foundry project (New Foundry experience toggled on) | Where the agent lives | | Owner or Foundry Project Manager on that project | To create agents and assign roles | | An APIM instance with System-assigned managed identity turned on | APIM must prove who it is to Foundry | | Contributor on the APIM instance | To add APIs and edit policies | | Postman (or curl) | To test | | ~45 minutes | Role assignments take a few minutes to propagate; budget for waiting |
| Placeholder | Meaning | Where to find yours | |---|---|---| | contoso-agents-poc | Foundry account name (the parent resource) | Foundry portal → Manage → Project details → Parent resource | | contoso-agents-poc | Foundry project name | Same page → Name. Often identical to the account name for the default project. | | helper-agent | The agent you're exposing | Whatever you named it | | contoso-apim | Your APIM instance name | Azure portal | | https://api.yourcompany.com | The public URL clients use to reach APIM | Either https://contoso-apim.azure-api.net or your custom domain / Front Door hostname |
Two things that will confuse you if nobody warns you Foundry's A2A endpoint requires Entra authentication for everything, including reading the agent card. Anything that tries to fetch it anonymously fails. APIM's import wizard does exactly that, so it will fail, and that's expected. We handle it. Foundry serves A2A protocol v0.3 by default unless you ask for v1.0 with a header. We'll set that header in APIM so clients don't have to think about it.
A1. Create the agent (skip if you already have one) Open ai.azure.com. Make sure the New Foundry toggle (top right) is on. Open your project → Build → Agents → + Create agent. Name it helper-agent. Pick a model (any deployed chat model — gpt-4o-mini is fine). In Instructions, write something real. A blank agent answers like a generic chatbot, which makes later testing meaningless. Example:
> You answer questions about company holiday policy. Be brief. If asked anything else, say it's outside your scope. Click Save (top right). This creates version 1. The agent's endpoint is live from this moment — there is no separate "publish" step.
The agent card is a small JSON document that tells other agents what this one can do. Creating it in the portal also turns on the A2A protocol for the agent. Open helper-agent → Details tab. Find the A2A / Agent card section and click Create an agent card (it's marked Preview). Fill it in. Write it for a machine that has to decide whether to call you, not for a human:
| Field | What to put | Example | |---|---|---| | Name | Pre-filled | helper-agent | | Description | 1–2 sentences: what it answers, what it doesn't | Answers questions about company holiday and leave policy. Does not handle payroll or IT. | | Skill name | Short noun phrase | Holiday policy queries | | Tags | Comma-separated keywords | holiday, leave, policy, hr | | Skill description | What a request looks like, what comes back | Given a question about leave or holidays, returns the relevant policy answer. | | Example prompts | 3–4 real ones, one per line | How many days of annual leave do I get? | Save.
That's the Foundry side done. Your agent now accepts A2A requests at the URL you copied earlier — from anyone holding a valid Entra token with the right role. Next we make APIM that someone.
B1. Open the A2A wizard Azure portal → your APIM instance (contoso-apim) → left menu APIs → + Add API. Find the tile A2A Agent. Click it.
Don't see the tile? A2A support arrived for v2 tiers first and was extended to classic tiers in the June 2026 release. Check your tier and that the instance is updated. If it's genuinely absent, stop here — the rest of this article won't apply.
B2. Paste the agent card URL (and watch it fail on purpose) In URL, paste the card URL — that's your A2A base URL with /agentCard/v1.0 on the end: Click Next. You'll see a red banner: "We couldn't retrieve the agent card, possibly due to a wrong url or your network configuration. Enter the agent API details manually below."
This is expected. APIM fetched the card anonymously; Foundry said no. The URL is not wrong. Carry on.
| Field | Value | |---|---| | Protocol | JSON-RPC (pre-selected, greyed out — APIM only supports this one) | | Runtime URL (JSON-RPC) | Your A2A base URL — the one without /agentCard/v1.0 | | Agent ID | helper-agent | | Display name | Helper Agent | | Name | helper-agent | | Description | Anything | | Products | Leave empty for now | | Base path | agents/helper-agent |
As you type the base path, the two read-only URLs underneath update to: Base URL (JSON-RPC): https://contoso-apim.azure-api.net/agents/helper-agent Agent card URL: https://contoso-apim.azure-api.net/agents/helper-agent/agent-card.json