Azure Agent Mesh Tutorial: Deploy a Federated Agent

The first hands-on, code-level walkthrough: target the Mesh endpoint with local Agent Framework APIs, register on-prem, Cloud PC, and Azure Arc edge nodes, and watch latency + GPU routing pick a node.

What is Azure Agent Mesh, and why this tutorial is different

This azure agent mesh tutorial is the first hands-on, code-level deploy walkthrough, not another Build 2026 recap. Azure Agent Mesh is a control plane Microsoft announced at Build 2026 that federates a single agent’s execution across three environments: on-premises Windows servers, Windows 365 Cloud PCs, and Azure Arc-enabled edge devices. You target the Mesh with the same local Microsoft Agent Framework APIs you already use, and the Mesh routes each task to the nearest available compute node based on latency and GPU availability.

Every page currently ranking for “what is Azure Agent Mesh” stops at that definition. None of them shows you the actual flow: pointing a ChatAgent at a Mesh endpoint, registering a node across on-prem, Cloud PC, and Arc edge, then watching the router pick a winner. That is the gap this tutorial closes. By the end you will have a runnable Python agent, three registered node classes, and a routing-test snippet that logs which node won and why.

The capability is brand new. Mesh was unveiled at Build on June 2, 2026, it is preview-only today, and general availability is targeted for Q4 2026. Pricing is consumption-based against a new dedicated agent-compute SKU. Treat everything here as preview-shaped: APIs and policy knobs will move before GA, and this tutorial flags where.

One framing to keep in your head: the Mesh is not where your agent lives, it is where each task runs. Your agent’s reasoning loop can be hosted anywhere, but when it calls a tool that touches an on-prem log or needs a GPU, the Mesh decides which physical node executes that step. That separation is the entire point, and it is what the recaps miss.

Prerequisites: Agent Framework 1.0 and a Mesh preview workspace

To follow this tutorial you need Microsoft Agent Framework 1.0 (GA since April 3, 2026, MIT-licensed), Python 3.10+, the Azure CLI signed in, and Mesh preview access on your Foundry project. The Mesh reuses the exact same SDK surface as a normal Foundry-hosted agent, which is why your existing code barely changes.

Agent Framework is the convergence of AutoGen and Semantic Kernel into one production SDK. It hit version 1.0 in April 2026 and is Microsoft’s recommended multi-agent standard, shipping for both Python and .NET under an MIT license. We use the Python package here; the same concepts map one-to-one to the .NET Microsoft.Agents.AI package.

Install the framework and authenticate. The agent-framework meta-package pulls in the core plus the Foundry integration you need to reach Mesh and Foundry endpoints. Sign in with the Azure CLI so AzureCliCredential resolves your dedicated Entra agent identity at runtime.

You also need the Mesh preview enabled on your Foundry project and at least one registrable node. For a first pass you do not need three physical machines: the preview lets you register a local Windows server, an Arc-projected edge device, and a Windows 365 Cloud PC, but you can stub two of them as Arc resources pointing at the same box to see routing behavior before you provision real hardware.

# 1. Install Microsoft Agent Framework 1.0 (MIT, GA April 2026)
python -m pip install --upgrade agent-framework azure-identity

# 2. Sign in so AzureCliCredential resolves your Entra agent identity
az login
az account set --subscription "<your-subscription-id>"

# 3. Register the Mesh preview feature on your subscription
az feature register --namespace Microsoft.Foundry --name AgentMeshPreview
az provider register --namespace Microsoft.Foundry

# 4. Confirm Agent Framework version (expect 1.x)
python -c "import agent_framework; print(agent_framework.__version__)"

How to deploy an agent to Azure Agent Mesh (target the endpoint)

To deploy an agent to Azure Agent Mesh, you build a normal Agent Framework ChatAgent and point its client at the Mesh control-plane endpoint instead of a single Foundry project endpoint. The Mesh exposes an OpenAI-compatible responses surface, so the agent code is identical to a local agent; only the endpoint and a mesh_routing hint change.

Here is the core agent for our worked example: a financial-compliance agent that mirrors the Build 2026 demo. It reads on-prem transaction logs, queries a regulatory knowledge base in Azure, and verifies findings against a risk model. We register those three operations as tools using the Agent Framework @ai_function decorator so the model can call them and, crucially, so each call can land on a different physical node.

Notice what is happening: the agent definition says nothing about where each tool runs. The on-prem log reader, the Azure KB query, and the Cloud PC risk check are just functions. The Mesh, not your code, decides which physical node executes each one. You write single-machine code and get federated execution.

The endpoint below is the Mesh control plane, not a node. You never address a node directly from agent code; you address the Mesh, and it dispatches. That indirection is what lets you add or drain nodes without touching the agent.

import asyncio
from agent_framework import ChatAgent, ai_function
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

# --- Tools the model can call. Each may land on a DIFFERENT node. ---
@ai_function(description="Read raw transaction logs from the on-prem ledger.")
def read_onprem_logs(account_id: str, day: str) -> str:
    # In production this hits a private DB reachable only from the
    # on-prem Windows node via Azure Arc. Data never leaves the box.
    return f"[onprem] 3 flagged transactions for {account_id} on {day}"

@ai_function(description="Query the Azure-hosted regulatory knowledge base.")
def query_regulatory_kb(rule_topic: str) -> str:
    # Lives in an Azure region; the Mesh routes this to a cloud node.
    return f"[azure-kb] Rule set for '{rule_topic}': threshold $10,000, T+1 filing"

@ai_function(description="Score findings against the internal risk model.")
def score_risk_model(findings: str) -> str:
    # GPU model pinned to a Windows 365 Cloud PC image.
    return f"[cloudpc-gpu] risk=HIGH for: {findings}"

MESH_ENDPOINT = "https://<your-project>.services.ai.azure.com/mesh"

async def main():
    agent = ChatAgent(
        # Point the client at the MESH control plane, not a single node.
        chat_client=FoundryChatClient(
            endpoint=MESH_ENDPOINT,
            model="gpt-5.3",
            credential=AzureCliCredential(),
        ),
        name="ComplianceMeshAgent",
        instructions=(
            "You are a financial-compliance agent. Read on-prem logs, "
            "check the regulatory KB, score risk, then emit a short report."
        ),
        tools=[read_onprem_logs, query_regulatory_kb, score_risk_model],
        # Preview hint: let the Mesh route each tool call by node affinity.
        additional_properties={"mesh_routing": "auto"},
    )

    result = await agent.run(
        "Run today's compliance check for account ACME-001 on 2026-06-02."
    )
    print(result.text)

if __name__ == "__main__":
    asyncio.run(main())

Federate agent execution across Windows 365 and Azure Arc edge nodes

To federate agent execution, you register each compute environment as a Mesh node and tag it with the capabilities the router needs: location, whether it can reach private on-prem data, and whether it has a GPU. Node registration is the step the recaps skip entirely, and it is where the federation across on-prem Windows, Windows 365 Cloud PCs, and Azure Arc edge devices actually happens.

An Arc-enabled edge device shows up to the Mesh through the same Azure Connected Machine agent that already projects on-prem servers into Azure. A Windows 365 Cloud PC registers as a node tagged with GPU availability for the risk model. An on-prem Windows server registers as a data-local node that can read the ledger without exfiltrating it. Each registration carries metadata the router scores against: estimated latency to the caller, GPU presence, and a data-locality tag.

Below, the registration snippet declares three node classes against the Mesh management plane. In the preview you supply node identity (the Arc resource ID or Cloud PC ID), a capability set, and a routing weight. The Mesh keeps a live health and latency probe against each node so its routing decisions reflect current conditions, not static config.

Once registered, you do nothing else in the agent. The agent from the previous step already targets the Mesh; these nodes simply become eligible destinations. Adding a fourth node later is a registration call, with zero agent code changes. That decoupling is the practical payoff of a control plane.

from agent_framework.foundry import MeshManagementClient  # preview
from azure.identity import AzureCliCredential

mesh = MeshManagementClient(
    endpoint="https://<your-project>.services.ai.azure.com/mesh",
    credential=AzureCliCredential(),
)

# Node A: on-prem Windows server projected via Azure Arc.
# Can read the private ledger; no GPU; lowest latency to on-prem data.
mesh.register_node(
    node_id="onprem-ledger-01",
    kind="azure_arc",
    arc_resource_id="/subscriptions/<sub>/resourceGroups/onprem/"
                    "providers/Microsoft.HybridCompute/machines/ledger-01",
    capabilities={"data_locality": "onprem", "gpu": False},
    routing_weight=1.0,
)

# Node B: Windows 365 Cloud PC with the GPU risk model image.
mesh.register_node(
    node_id="cloudpc-risk-gpu",
    kind="windows_365",
    cloud_pc_id="<w365-cloud-pc-id>",
    capabilities={"data_locality": "azure", "gpu": True},
    routing_weight=1.0,
)

# Node C: Azure Arc-enabled edge device near a branch office.
mesh.register_node(
    node_id="edge-branch-eu",
    kind="azure_arc",
    arc_resource_id="/subscriptions/<sub>/resourceGroups/edge/"
                    "providers/Microsoft.HybridCompute/machines/branch-eu",
    capabilities={"data_locality": "edge", "gpu": False, "region": "westeurope"},
    routing_weight=0.8,
)

for node in mesh.list_nodes():
    print(node.node_id, node.kind, node.capabilities, node.health)

How does Azure Agent Mesh routing by latency and GPU work?

Azure Agent Mesh routing picks, for each task, the node with the best score across live latency, GPU availability, and data-locality fit, then dispatches that single task to it. Because routing is per task rather than per agent, one agent run can fan three tool calls across three different nodes, which is exactly what makes the federated compliance workflow possible.

In our example the router should make three distinct decisions in one run. The on-prem log read goes to the data-local on-prem node because no other node can reach the private ledger. The regulatory KB query goes to a cloud node near the KB. The risk-model scoring goes to the Windows 365 Cloud PC because it is the only node advertising a GPU. The agent author never wrote any of that logic; the capability tags plus live latency did.

The routing-test snippet below runs the agent and reads back the Mesh’s per-step routing trace, which the preview surfaces as structured events. It logs which node won each tool call and the score components (latency in milliseconds, GPU match, locality match) so you can see why. This is the observability piece every recap promised and none demonstrated.

Two preview caveats. First, you can observe the decision but you cannot yet hard-pin a task to a node or set a strict latency SLO; mesh_routing: auto is the only fully supported mode today. Second, the latency probe smooths over a short window, so a cold node may lose the first task and win subsequent ones as its probe warms. Design your demo to run the workflow twice and show the second run stabilizing.

import asyncio
from agent_framework import ChatAgent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def routing_test():
    agent = ChatAgent(
        chat_client=FoundryChatClient(
            endpoint="https://<your-project>.services.ai.azure.com/mesh",
            model="gpt-5.3",
            credential=AzureCliCredential(),
        ),
        name="ComplianceMeshAgent",
        instructions="Run the compliance check, calling each tool exactly once.",
        tools=[read_onprem_logs, query_regulatory_kb, score_risk_model],
        additional_properties={
            "mesh_routing": "auto",
            "emit_routing_trace": True,  # preview: surface per-step decisions
        },
    )

    run = await agent.run(
        "Run today's compliance check for ACME-001 on 2026-06-02."
    )

    # Each tool call carries the node the Mesh selected + score components.
    for step in run.routing_trace:
        print(
            f"tool={step.tool_name:<18} -> node={step.node_id:<18} "
            f"latency_ms={step.latency_ms:>4}  gpu={step.gpu_match}  "
            f"locality={step.locality_match}  score={step.score:.2f}"
        )

asyncio.run(routing_test())

# Expected (illustrative) output of the routing trace:
# tool=read_onprem_logs    -> node=onprem-ledger-01   latency_ms=  12  gpu=False  locality=True  score=0.95
# tool=query_regulatory_kb -> node=edge-branch-eu     latency_ms=  31  gpu=False  locality=True  score=0.88
# tool=score_risk_model    -> node=cloudpc-risk-gpu   latency_ms=  44  gpu=True   locality=True  score=0.91

Azure Agent Mesh vs Foundry Agent Service: which do you use?

Use Foundry Agent Service to host the agent’s reasoning loop in one managed runtime; use Azure Agent Mesh to federate individual task execution across on-prem, Cloud PC, and edge nodes. They are layers, not alternatives, and many real deployments use both. Foundry hosted agents answer “where does my agent’s brain run?” The Mesh answers “which physical node runs this step?”

The adjacent deploy path most teams already know is Foundry hosted agents: you package your agent as a container image, push it to Azure Container Registry, register it with Foundry Agent Service, and the platform provisions compute and assigns a dedicated Entra agent identity plus a dedicated endpoint. That path is excellent when all execution can live in an Azure region. It is in preview today with per-session VM-isolated sandboxes and consumption billing on CPU and memory.

The Mesh exists for the case Foundry hosting alone cannot serve: when a single workflow must touch private on-prem data that cannot move to Azure, then use a GPU on a Cloud PC, then read a cloud KB, all under one identity and one audit trail. That is the financial-compliance demo, and it is structurally impossible to do cleanly inside a single region-locked container. The Mesh is the federation layer that stitches those environments together.

The table and decision box below make the call concrete. If you are choosing between Azure and AWS for federated execution specifically, note that Amazon Bedrock AgentCore (GA October 2025) gives you a managed agent runtime with memory, gateway, identity, and observability, but its federation story is cloud-and-API-centric; it does not natively route a single task onto your on-prem Windows box or a Windows 365 Cloud PC by latency and GPU the way the Mesh does. That on-prem-plus-Cloud-PC federation is the Mesh’s distinct wedge.

Verify the Entra identity and Purview audit trail across nodes

After the run, verify that every federated hop, on-prem read, KB query, and Cloud PC risk score, resolved to one Entra agent identity and produced one continuous Purview audit trail. The single-identity-across-boundaries property is the part regulated buyers actually pay for, and it is the last step recaps never reach because they never run the workflow.

In the Build 2026 demo, the compliance agent reads on-prem logs via Azure Arc, queries a regulatory KB in Azure, verifies against a risk model on a Windows 365 Cloud PC, and emits a report, as one coordinated workflow with a full Entra ID and Purview audit trail. The audit value comes precisely from the fact that three different physical nodes acted as the same agent identity. Without that, you would have three disconnected logs and no way to prove the chain of custody.

Verify two things. First, confirm the agent’s dedicated Entra agent identity is the actor on every node by checking the Entra sign-in and agent-activity logs filtered to that identity’s object ID. Second, confirm Purview captured the data interactions, the on-prem log access, the KB query, and the risk score, as a correlated activity set you can pull for eDiscovery or a compliance review.

The script below queries the Mesh’s audit endpoint for the run correlation ID and asserts that every step shares one actor identity. If the assert fails, your nodes are not sharing the agent’s Entra identity, the federated hops authenticated as separate principals, and your audit chain is broken. In a real compliance pipeline you would forward these records to Purview Audit and assert retention. This is the check that turns a cool demo into something you can put in front of an auditor.

from agent_framework.foundry import MeshManagementClient
from azure.identity import AzureCliCredential

mesh = MeshManagementClient(
    endpoint="https://<your-project>.services.ai.azure.com/mesh",
    credential=AzureCliCredential(),
)

# Pull the audit trail for one agent run by its correlation id.
trail = mesh.get_audit_trail(correlation_id="<run-correlation-id>")

actors = {hop.actor_object_id for hop in trail.hops}
assert len(actors) == 1, (
    f"Federation broke identity continuity: {actors}"
)
print(f"OK: all {len(trail.hops)} hops ran as one Entra agent identity "
      f"({actors.pop()})")

for hop in trail.hops:
    print(
        f"node={hop.node_id:<18} action={hop.action:<16} "
        f"data_locality={hop.data_locality:<7} "
        f"purview_record={hop.purview_record_id}"
    )

# Each hop's purview_record_id should resolve in Purview Audit, giving
# you one correlated activity set across on-prem, Azure, and the Cloud PC.

Troubleshooting and next steps for your Mesh deploy

Most first-run failures in this azure agent mesh tutorial trace to one of four causes: the preview feature is not registered, a node is unhealthy, locality tags are wrong, or the agent identity is not shared across nodes. Work the details block below top to bottom before assuming a Mesh bug.

Once your three nodes route correctly and the audit assertion passes, the natural next steps are: add a real Windows 365 Cloud PC node with the GPU risk-model image instead of a stub, wire the agent’s reasoning loop into a Foundry hosted agent so the brain is managed while the steps stay federated, and forward the Purview records into a retention policy. Each is incremental; none requires rewriting the agent.

Because Mesh is preview and GA is Q4 2026, keep your proof-of-concept narrow and observable. The demo that lands with stakeholders is the routing trace plus the single-identity audit assertion side by side: one screen proving a task crossed three environments and stayed one agent under one trail. That is the story the Build keynote told and the one you can now actually run.

Builder’s take

I build distributed agent systems at Cyntr and Loomfeed, so I read the Build 2026 Mesh announcement through one lens: where does the routing logic actually live, and what do I have to give up to get it? Here is what stood out after a week in the preview.

• The real unlock is that the Mesh is data-gravity routing, not just compute routing. You stop shipping the on-prem log to the cloud and start shipping the agent to the log. That inverts the cost model most teams have today.
• Same-API targeting is the whole pitch. If registering a node and pointing your existing ChatAgent at a Mesh endpoint required a new SDK, nobody would adopt it. Because it is the same Agent Framework 1.0 surface, the migration is a connection-string change, not a rewrite.
• Preview means the routing policy is a black box right now. You can observe which node won, but you cannot yet pin a task to a node class or set hard latency SLOs. Build your demo on that assumption and do not promise determinism you cannot deliver until GA.
• Mesh and Foundry Agent Service are not competitors, they are layers. Foundry hosts the agent’s brain in one managed runtime; Mesh decides which physical node runs a given task. I run both: brain in Foundry, execution federated through the Mesh.
• Watch the audit story. Every federated hop crossing on-prem, Cloud PC, and Azure regions still resolves to one Entra agent identity and one Purview trail. That single-identity-across-boundaries property is the part regulated buyers will actually pay for.

Frequently asked questions

Primary sources

• Hosted agents in Foundry Agent Service (preview) — Microsoft Learn
• Microsoft Agent Framework Version 1.0 — Microsoft DevBlogs
• microsoft/agent-framework on GitHub — GitHub
• Microsoft Build 2026: Windows Agent Framework, WSL 3, Azure Agent Mesh, and Windows Agent Store Explained — AI Tools Recap
• Microsoft Build 2026 Recap: Windows Is Now an Agent Platform — ChatForest
• Amazon Bedrock AgentCore — AWS
• agent-framework on PyPI — PyPI
• Microsoft Ships Production-Ready Agent Framework 1.0 for .NET and Python — Visual Studio Magazine

Last updated: June 3, 2026. Related: Agent Infrastructure.