Deploying an AG-UI Agent on Microsoft Foundry's MicroVM Hosted Agents

Geert Baeke has documented a working deployment of an AG-UI agent server on Microsoft Foundry's new hosted agents, the MicroVM-based version announced April 22, 2026. The walkthrough covers the entire pipeline — a six-line Dockerfile, two deployment manifests, and a Next.js chat client — with source code published on GitHub (github.com/gbaeke/hostedagentv2).

AG-UI is a wire protocol in which an agent emits typed events like RUN_STARTED, TEXT_MESSAGE_START, and TOOL_CALL_* over Server-Sent Events, leaving the UI to decide how to render them. A previous build used Microsoft Agent Framework; this deployment addresses the follow-up question of where to actually host such an agent.

Foundry hosted agents take a container image and a small manifest, then run it behind a managed endpoint inside a Foundry project. The platform handles HTTPS termination, Entra ID authentication, a managed identity so the agent can call Azure OpenAI without API keys (via DefaultAzureCredential), and injection of FOUNDRY_PROJECT_ENDPOINT and APPLICATIONINSIGHTS_CONNECTION_STRING into the container environment. No agent SDK is required — only the right HTTP contract. The new version runs one MicroVM per session, with state such as filesystem contents accessible to that session; sessions are retired after 15 minutes idle.

Two interaction protocols are available, and the choice matters. The Responses protocol follows the OpenAI request format and lets Foundry own conversation history server-side. The Invocations protocol is transport-only: each call is a POST /invocations, the agent owns the turn end-to-end, and the container streams whatever response format it likes. For an AG-UI agent, Invocations is the recommended choice, since AG-UI SSE events pass through Foundry unmodified.

The demo agent relies on three pieces: azure-ai-agentserver-invocations, a thin Starlette host that exposes POST /invocations on port 8088; pydantic-ai for model binding and a weather tool; and pydantic_ai.ag_ui.handle_ag_ui_request, which translates an agent run into the AG-UI SSE stream. The Azure OpenAI base URL is derived by stripping the path from FOUNDRY_PROJECT_ENDPOINT, so no separate endpoint variable is needed. The Dockerfile is six lines.

Deployment is a single azd command with two manifests. agent.yaml is the runtime ContainerAgent spec Foundry reads; agent.manifest.yaml is the template azd consumes, with model deployment placeholders substituted at deploy time. The image is built remotely in ACR and pushed, and the agent is registered with Foundry.

The web client is Next.js 14 with CopilotKit. The browser holds no credentials: a server-side route authenticates to Foundry with DefaultAzureCredential over Entra ID, then forwards requests through HttpAgent. A session ID is generated once per browser tab and passed in the X-Foundry-Session-Id header, so each conversation stays in one sandbox. CopilotKit intercepts the agent's get_weather tool call by name and renders a weather card instead of raw JSON.

Several limitations are documented. A page refresh loses the conversation: history lives only in React state and is replayed each turn, with nothing stored by runtime, agent, or model. Durable history would require the Responses protocol, which would mean abandoning AG-UI. The Foundry playground UI does not work meaningfully with Invocations, since the protocol expects a specific payload. Trace telemetry for Invocations is "not very useful out of the box," though session logs and App Insights data are available.