Blog Post

Microsoft Developer Community Blog
13 MIN READ

Building and Deploying Microsoft Hosted Agents to Microsoft Teams

Lee_Stott's avatar
Lee_Stott
Icon for Microsoft rankMicrosoft
Jul 29, 2026

A practical, engineer-to-engineer guide to taking an AI agent from a developer laptop, into Microsoft Foundry Agent Service, and out to end users inside Microsoft Teams and Microsoft 365 — using the BRK241 FibreOps reference implementation as a worked example.

Introduction: the hard part is no longer building the agent

Two years ago, wiring an LLM to a couple of tools felt like the summit. It isn't any more. Frameworks, hosted models, and function-calling have made the build step almost routine. The problem has quietly moved downstream. The genuinely hard questions today are operational:

  • Where does the agent run when it's no longer on your machine?
  • What identity does it use to call enterprise systems, and who granted it?
  • How does a platform team scale, monitor, and roll it back?
  • How do business users actually reach it without learning a new tool?
  • Who signed off on it touching production data?

A prototype answers none of these. A production agent platform answers all of them, repeatably, for every agent an organisation ships. That shift — from a clever notebook to a governed, observable service that lands in the tools people already use — is the subject of this article.

We'll use a single narrative to keep it concrete: FibreOps, the BRK241 "Autonomous Fibre Outage Response" system. It ingests optical line terminal (OLT) telemetry, analyses incidents, files tickets in Dynamics 365 Field Service, posts Adaptive Cards to Microsoft Teams, and dispatches engineers — all through role-specialised agents. The full source is on GitHub. The story runs on three verbs: Build → Run → Distribute.

Section 1: Building the agent

An agent is not one mega-prompt. FibreOps is deliberately factored into three role-specialised agents behind a single orchestrator, each with its own tool surface, its own system instructions, and a strict output contract:

  • IncidentAnalysisAgent — classifies severity, finds probable cause, and pulls the correct standard operating procedure (SOP).
  • NetOpsCoordinatorAgent — files the D365 incident and posts the Teams outage notice.
  • FieldDispatchAgent — selects the best engineer by skill, region and shift, books the resource, and updates Teams.

The Coordinator hands off to Dispatch with a literal HANDOFF:DISPATCH token rather than a fuzzy "I think we should…". Hard contracts between agents are how you stop them inventing work.

Microsoft Agent Framework

The agents are built with the Microsoft Agent Framework (MAF). The key design decision in the reference implementation is that all three backends honour one contract — await agent.run(prompt) -> response — so the orchestrator never knows or cares where reasoning actually happens:

  • local — a deterministic LocalAgent shim with no LLM, so the demo runs with zero Azure credentials.
  • foundry — agent_framework.Agent + FoundryChatClient, definition resolved locally. Ideal while iterating on prompts.
  • hosted — agent_framework_foundry.FoundryAgent bound to a Prompt Agent published to Foundry Agent Service. This is the production path.

Building a Foundry-backed agent is just a client plus instructions plus typed tools:

from agent_framework import Agent
from agent_framework_foundry import FoundryChatClient
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=settings.azure_ai_project_endpoint,
    model=settings.azure_ai_model_deployment,   # e.g. gpt-4.1-mini
    credential=DefaultAzureCredential(),         # no connection strings, ever
)

agent = Agent(
    client=client,
    instructions=INCIDENT_ANALYSIS_INSTRUCTIONS_V1,
    name="IncidentAnalysisAgent",
    tools=[lookup_sop, recall, remember, web_iq_search, work_iq_search],
)

Note the DefaultAzureCredential. There are no keys or connection strings anywhere in the reasoning path — identity flows from Microsoft Entra ID. Keep that in mind; it becomes the backbone of the governance story later.

Tool calling and MCP

Every tool is a typed Python function. Foundry sees the JSON schema derived from the signature; the runtime executes the Python. That separation matters: the published agent definition stores only the model and instructions, while the implementations are supplied by the runtime on every call. The same in-process tools (Teams, D365, dispatch, knowledge, memory) run identically whether the agent is local or hosted.

Beyond your own functions, Foundry agents can draw on hosted toolbox tools (web_search, code_interpreter) and Model Context Protocol (MCP) servers. MCP is the open standard for exposing tools, resources and prompts to agents over a uniform protocol, so an enterprise can stand up an MCP server once and let every agent consume it. In FibreOps this is config-gated — set FIBREOPS_FOUNDRY_TOOLBOX=1 and the incident analyst gains live web search alongside its Web IQ / Work IQ connectors, with no code change.

Grounding strategies

FibreOps grounds reasoning three ways, in layers:

  • Retrieval over owned knowledge — SOPs (markdown) and the fibre-node topology graph, looked up by the analysis agent.
  • Foundry IQ — Web IQ for public context (roadworks, weather, power) and Work IQ for enterprise context (site surveys, SLA tiers, competency matrix).
  • Procedural memory — prior incidents for a node, recalled before analysis so the agent learns from history.

Crucially, when the IQ endpoints are unset the tools fall back to deterministic fixtures so the agent always grounds. Grounding that silently fails is worse than no grounding; design your fallbacks explicitly.

Local development, testing and evaluation

The whole system runs from one command with no cloud dependency:

# Deterministic local backend — no Azure credentials required
python -m fibreops.demo --signals 3 --backend local

Every run is persisted as a JSON document — the input signal, every agent step, every tool call, every output, every ticket. That single artefact shape feeds three consumers: structured logs, the local optimiser, and Foundry Evaluators. The optimiser scores each run against a five-criterion rubric (was the analysis complete, was severity consistent with customer impact, did a ticket land, did dispatch policy match severity, was an SOP cited) and writes back concrete improvement suggestions. That evaluation loop — not the first working demo — is what turns a prototype into a system you can keep improving.

Section 2: Deploying to Microsoft Foundry Agent Service

Microsoft Foundry Agent Service is the managed runtime that hosts your agents. It gives you a secure, isolated execution environment, an agent runtime that speaks the OpenAI-compatible Responses API, plus hosted memory, toolboxes, knowledge integrations, and observability — without you operating any of it.

FibreOps demonstrates the two hosting shapes Foundry offers.

Shape 1 — Prompt Agents

A Prompt Agent stores a model deployment plus system instructions as an immutable, versioned definition in Foundry. Publishing is a one-time step per change:

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential

pc = AIProjectClient(endpoint=endpoint,
                     credential=DefaultAzureCredential(),
                     allow_preview=True)

pc.agents.create_version(
    agent_name="fibreops-incident-analysis",
    definition=PromptAgentDefinition(
        model=model_deployment,
        instructions=INCIDENT_ANALYSIS_INSTRUCTIONS_V1,
    ),
    description="FibreOps incident analysis agent",
)

At run time you bind to the published version with a FoundryAgent, and — as noted above — the runtime supplies the tool implementations. Prompt versioning (instructions_v1, _v2, _v3) is where the optimiser's suggestions land, closing the improvement loop inside the platform.

Shape 2 — Containerised hosted agents

The BRK241 hero path packages the entire analyse → coordinate → dispatch flow as a single hosted agent: a container that serves the Responses /responses contract on port 8088, deployed straight into your Foundry project. The Agent Framework agent is wrapped by ResponsesHostServer:

from agent_framework_foundry_hosting import ResponsesHostServer

def main() -> None:
    server = ResponsesHostServer(build_system_agent())
    # Foundry sets the reserved PORT env var inside the sandbox
    server.run(host="0.0.0.0", port=8088)

The container is declared in agent.yaml — kind: hosted, the image reference, the per-session sandbox size (0.5/1 Gi, 1/2 Gi or 2/4 Gi), the protocol version, and only user-declared environment variables. You never hard-code FOUNDRY_* values or the Application Insights connection string; the platform injects those at run time. Deployment registers the image as an immutable version and polls until active:

details = pc.agents.create_version(
    agent_name="fibreops-outage-response",
    definition=HostedAgentDefinition(
        protocol_versions=[ProtocolVersionRecord(
            protocol=AgentProtocol.RESPONSES, version="1.0.0")],
        cpu="1", memory="2Gi",
        container_configuration=ContainerConfiguration(image=image),
        environment_variables={"MODEL_DEPLOYMENT_NAME": model_deployment},
    ),
)

From local execution to managed hosting

The migration path is deliberately gentle because the contract never changes. A developer iterates locally against LocalAgent, moves to the foundry backend to test real prompts, then publishes Prompt Agents or builds and deploy-hosteds the container. The orchestrator code is byte-for-byte identical across all three. That property — same code path local for dev, hosted in Foundry for prod — is the single most important thing to preserve when designing your own agents.

Scaling, memory, toolboxes, knowledge and observability

  • Scaling — Foundry provisions a per-session sandbox and a dedicated Entra agent identity per hosted-agent version; you size the sandbox in agent.yaml and let the platform handle isolation.
  • Memory — set FOUNDRY_MEMORY_STORE_NAME and a FoundryMemoryProvider is attached as a context provider so agents read and write learned procedures in Foundry's hosted store; unset, they use local SQLite. No code change.
  • Toolboxes & knowledge — hosted web_search, code interpreter, MCP, and Web/Work IQ connectors are curated per role and merged with your Python tools.
  • Observability — the agent emits OpenTelemetry spans; set APPLICATIONINSIGHTS_CONNECTION_STRING (injected by the platform for hosted agents) and every agent decision, tool call and latency is queryable in Application Insights.

Section 3: IT and development responsibilities

Successful agent deployments need both developer velocity and platform governance. The failure mode at either extreme is familiar: developers who can't ship because every request routes through a ticket queue, or a free-for-all where nobody can say what identity an agent runs as. The workable model draws a clean line of responsibility.

ConcernDeveloper / Agent teamIT / Platform team
IdentityUse DefaultAzureCredential; never embed secrets; declare the scopes the agent needsProvision the managed / Entra agent identity; own the app registration and consent
Access controlRequest least-privilege roles for the tools the agent callsGrant RBAC at the correct scope; run role-assignment scripts; enforce approvals
SecurityValidate inputs, handle tool failures cleanly, avoid data exfiltration in promptsDisable ACR admin, enforce managed-identity pulls, network controls, Key Vault for secrets
ComplianceKeep decisions explainable and replayable (the JSON run record)Data-residency, retention, audit, Responsible AI review sign-off
MonitoringEmit structured traces + OTel spans; define the rubricOwn Application Insights / Log Analytics, alerting, dashboards, SLOs
CostRight-size the sandbox and model deployment; cache groundingBudgets, quota, token-consumption monitoring, chargeback
LifecycleVersion prompts and images; feed the optimiser back into new versionsEnvironment promotion (dev → test → prod), rollback, deprecation

The reference implementation encodes this split honestly. The Bicep template does not create role assignments, because most deployers only hold Contributor. Instead a subscription Owner runs scripts/grant-mi-roles.ps1 once to grant the App Service's identity exactly the roles it needs — Event Hubs Data Owner, Key Vault Secrets User, AcrPull, Azure AI Developer, and Cognitive Services OpenAI User — and no more. That is least privilege made operational.

Section 4: Publishing to Microsoft Teams and Microsoft 365

An agent nobody can reach has no value. The final verb — Distribute — puts the agent where users already work. FibreOps reaches Teams two ways.

The lightweight path: Adaptive Cards via Incoming Webhook

The NetOps coordinator posts outage notices and status updates to a Teams channel as Adaptive Cards through an Incoming Webhook. Any unconfigured channel is logged to state/teams_outbox.jsonl, so the same code runs in a demo and in production — you only change the webhook target. This is the fastest way to get agent output into Teams and is ideal for notifications and human-in-the-loop review.

The rich path: a declarative agent for Microsoft 365 Copilot

To make the agent conversational and discoverable across Teams, Microsoft 365 Copilot and copilot.microsoft.com, FibreOps ships as a declarative agent plus an API plugin action. One command builds the sideload-ready package:

python -m fibreops.demo publish-m365 --out dist/m365
#  wrote declarativeAgent.json  (name, description, conversation starters)
#  wrote fibreops-action.json   (API plugin -> {base_url}/openapi.json)
#  wrote manifest.json          (Teams app manifest)
#  wrote color.png / outline.png (icons)
#  wrote fibreops-copilot.zip   (upload this)

The declarative agent declares metadata, conversation starters and a capability set; the action plugin proxies tool calls to the deployed FastAPI app via its OpenAPI document. Set M365_ACTION_BASE_URL to the app's public HTTPS root before publishing — the CLI warns when the placeholder is still in effect. That single environment variable is the only thing that flips the package from demo to production.

The end-to-end distribution workflow

Conceptually, the artefact travels a fixed pipeline:

Developer laptop
   │  build + test (local backend)   →  publish Prompt Agent / deploy hosted container
   ▼
Microsoft Foundry Agent Service
   │  hosted agent, secure sandbox, Entra agent identity, observability
   ▼
Teams App package  (fibreops-copilot.zip)
   │  Teams Admin Center → Manage apps → Upload   (or M365 Admin Center → Integrated apps)
   ▼
Microsoft 365 tenant
   │  admin approval, availability policy, targeted rollout
   ▼
End user in Teams / M365 Copilot

Enterprise rollout is rarely "publish to everyone". The realistic pattern is a staged one: sideload to a pilot group, gather feedback and optimiser scores, then widen availability through Teams app-permission and app-setup policies to department, then tenant. Because the package carries publisher metadata and the declarative schema, IT can review it exactly like any other line-of-business app.

Section 5: Enterprise governance

Governance is not a bolt-on; in this architecture it's a property of the platform. The pillars:

  • Entra ID integration and agent identity — every hosted agent version gets a dedicated Entra agent identity. Nothing authenticates with a shared key. DefaultAzureCredential means the same code picks up a developer's identity locally and the managed identity in production.
  • RBAC at the right scope — roles are granted to identities, not baked into images. Deploying a hosted agent requires Azure AI Project Manager at project scope; the Foundry project identity needs AcrPull on the registry to pull the container. Least privilege is enforced, not assumed.
  • Auditability — the JSON run record plus OpenTelemetry spans in Application Insights give you a replayable, per-incident audit trail. You can reconstruct exactly which SOP was cited, which engineer was chosen, and why severity was escalated.
  • Data boundaries — the mock D365 is a drop-in for a real Dataverse environment; grounding sources are enterprise connectors (Work IQ) kept inside the tenant boundary. Nothing leaves the subscription without an explicit connector.
  • Responsible AI — the Adaptive Card JSON can be pasted into the Adaptive Cards designer for governance review; the evaluation rubric makes quality measurable; explicit grounding fallbacks prevent silent failure.
  • Production readiness — immutable versioning, one-command rollback (delete a version), managed-identity-only image pulls, and disabled ACR admin credentials are all first-class in the reference deployment.

Section 6: Reference architecture

The following diagram shows the production topology — users on the left, enterprise systems and controls on the right, with Foundry Agent Service at the centre hosting the agent.

flowchart LR
    User["NOC operator / business user"]

    subgraph M365["Microsoft 365 tenant"]
        Teams["Microsoft Teams(Adaptive Cards + declarative agent)"]
        Copilot["Microsoft 365 Copilot"]
    end

    subgraph Foundry["Microsoft Foundry Agent Service"]
        Hosted["Hosted AgentOutage Response System(secure per-session sandbox)"]
        Runtime["Agent runtime(Responses API)"]
        Memory["Hosted memory + toolboxes"]
    end

    subgraph Enterprise["Enterprise data & tools"]
        MCP["MCP servers / web_search"]
        D365["Dynamics 365 Field Service"]
        EventHub["Azure Event Hubs(OLT telemetry)"]
        Knowledge["SOPs + topology + Web/Work IQ"]
    end

    subgraph Ops["Cross-cutting"]
        Obs["ObservabilityApp Insights / OTel"]
        Gov["GovernanceEntra ID · RBAC · audit"]
    end

    User --> Teams
    User --> Copilot
    Teams --> Runtime
    Copilot --> Runtime
    Runtime --> Hosted
    Hosted --> Memory
    Hosted --> MCP
    Hosted --> Knowledge
    Hosted --> D365
    EventHub --> Hosted
    Hosted -.->|Adaptive Cards| Teams
    Hosted --> Obs
    Gov -.->|identity & policy| Foundry
    Gov -.->|identity & policy| Enterprise

Read the solid arrows as the control/orchestration flow and the dashed arrows as governance and outbound notifications. The point of the diagram is that governance (Entra ID, RBAC, audit) applies across every component, and observability captures every agent decision — neither is optional plumbing.

Section 7: What production looks like

Picture the FibreOps rollout at a national fibre operator, with the four personas doing their part:

  1. Developers build the three agents and the orchestrator on their laptops against the local backend — no cloud, no credentials, deterministic tests. They tune prompts against the foundry backend, watch the optimiser rubric climb from 0.90 to 1.0 as they add the ">5,000 customers ⇒ escalate to critical" rule, and commit a new instruction version.
  2. The platform team deploys the container to Foundry Agent Service via scripts/deploy-hosted-agent.ps1, which builds the image in ACR, pushes it, and registers an immutable version. They provision the Event Hub, Key Vault, Log Analytics and Application Insights from Bicep, and size the sandbox at 1 vCPU / 2 GiB.
  3. IT approves the workload: a subscription Owner grants the managed identity its five least-privilege roles, hardens the App Service to pull via managed identity, disables ACR admin, and signs off the Responsible AI review using the replayable run records and the Adaptive Card previews. They sideload fibreops-copilot.zip to a pilot channel first.
  4. Business users consume it inside Teams. When an OLT in London loses light, an Adaptive Card appears in the NOC channel within seconds — severity, probable cause, ticket ID, and the dispatched engineer's ETA — with no human having read a dashboard, opened a ticket, or phoned a dispatcher. If Foundry ever wobbles, the same system falls back to the deterministic local agent with an identical trace shape.

Every integration but D365 is live in the demo, and D365 is a one-variable swap to a real Dataverse endpoint. That is the whole point: the demo and production differ by configuration, not by code.

Key takeaways

  • Design for one contract. If agent.run(prompt) behaves identically local, foundry-backed and hosted, migration to production is configuration, not a rewrite.
  • Factor agents by role with hard handoff contracts. Literal tokens like HANDOFF:DISPATCH beat fuzzy natural-language handoffs and stop agents inventing work.
  • Never embed secrets. DefaultAzureCredential + Entra agent identities give you keyless auth that works the same everywhere.
  • Make every run replayable. A single JSON artefact that feeds logs, evaluation and audit is worth more than any dashboard.
  • Ground explicitly, and design your fallbacks. Grounding that fails silently is a liability; deterministic fixtures keep the agent honest.
  • Split responsibility cleanly. Developers own velocity and quality; the platform team owns identity, scale, cost and promotion. Encode the split in scripts, not tribal knowledge.
  • Version prompts and images immutably. Rollback should be "delete a version", and the optimiser's suggestions should land as the next version.
  • Distribute where users already are. Adaptive Cards for notifications, a declarative agent for conversation and discovery across Teams and M365 Copilot.
  • Roll out in stages. Pilot channel → department → tenant, gated by app policies and real optimiser scores.

Resources

Clone the repo, run python -m fibreops.demo --signals 3 --backend local, and watch the analyse → coordinate → dispatch loop close. Then wire in your own Foundry project and take it all the way to Teams. Go build something.

Published Jul 29, 2026
Version 1.0
No CommentsBe the first to comment