Microsoft Foundry details containerized agent A2A endpoint pattern

Microsoft has published documentation showing how to expose a locally built, containerized agent as a discoverable endpoint speaking the Agent-to-Agent (A2A) protocol through Azure Foundry. The pattern lets hosted agents inherit authentication, ingress management, A2A transport, and agent-card discovery from the platform, rather than reimplementing them in application code.

The central design point is a separation between two independent configuration planes. The control plane—configured through azure.yaml and the Azure Developer CLI—declares the agent version, image, resources, and which protocols the container implements. The data plane, configured through endpoint commands, controls the live endpoint's authentication, enabled protocols, and published agent card. Protocols declared in one but not the other are not available to callers; both declarations are required.

The documentation is explicit about a common mistake: adding application-level A2A routes to a Foundry-hosted container. Foundry owns the A2A transport layer, so the container itself serves plain HTTP on port 8088 with TLS terminating upstream. The container is expected to provide a fast, shallow GET /readiness check, handle SIGTERM with graceful drain, and emit OpenTelemetry signals. The guidance warns against putting downstream dependency probes in /readiness—a model or database outage should not trigger a platform recycle of a container that can still report requests correctly. Deep diagnostics belong on a separate endpoint.

The agent exposes two protocol handlers pointing at the same service: invocations, the direct native contract, and responses, the chat-shaped protocol that Foundry uses as the landing zone for incoming A2A traffic. The documentation stresses that both handlers should share one service so a request produces the same decision and error envelope regardless of which path it arrived through. The examples include a request-validation agent that returns verdicts like approve, reject, or needs_human_review.

The protocol configuration is asymmetrical. responses and invocations appear in the agent version because the container implements them. a2a appears only at the endpoint level because Foundry provides that transport. The responses protocol must be enabled before A2A, since it is the bridge target.

Discovery works through a published agent card that other agents and model-driven planners retrieve. The documentation advises writing it for routing rather than marketing: what the agent accepts, what it returns, and when another agent should choose it.

The feature carries constraints. Only text modality is supported; file data and non-text modalities are not. Streaming responses via server-sent events are not supported. Agents that do not use the responses protocol cannot be exposed as A2A endpoints.

A successful deployment is not enough if the endpoint protocols were never applied. Microsoft's troubleshooting checklist begins with checking that the container listens on port 8088, that both version-level protocols are declared, and that the endpoint update ran after the agent version was deployed. A 404 on the agent-card URL usually means the endpoint update did not apply.