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 deterministicLocalAgentshim 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.FoundryAgentbound 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.yamland let the platform handle isolation. - Memory — set
FOUNDRY_MEMORY_STORE_NAMEand aFoundryMemoryProvideris 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.
| Concern | Developer / Agent team | IT / Platform team |
|---|---|---|
| Identity | Use DefaultAzureCredential; never embed secrets; declare the scopes the agent needs | Provision the managed / Entra agent identity; own the app registration and consent |
| Access control | Request least-privilege roles for the tools the agent calls | Grant RBAC at the correct scope; run role-assignment scripts; enforce approvals |
| Security | Validate inputs, handle tool failures cleanly, avoid data exfiltration in prompts | Disable ACR admin, enforce managed-identity pulls, network controls, Key Vault for secrets |
| Compliance | Keep decisions explainable and replayable (the JSON run record) | Data-residency, retention, audit, Responsible AI review sign-off |
| Monitoring | Emit structured traces + OTel spans; define the rubric | Own Application Insights / Log Analytics, alerting, dashboards, SLOs |
| Cost | Right-size the sandbox and model deployment; cache grounding | Budgets, quota, token-consumption monitoring, chargeback |
| Lifecycle | Version prompts and images; feed the optimiser back into new versions | Environment 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.
DefaultAzureCredentialmeans 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:
- Developers build the three agents and the orchestrator on their laptops against the
localbackend — no cloud, no credentials, deterministic tests. They tune prompts against thefoundrybackend, 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. - 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. - 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.zipto a pilot channel first. - 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:DISPATCHbeat 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
- Reference implementation: github.com/leestott/BRK241-frontier
- Microsoft Agent Framework overview
- Microsoft Foundry Agent Service
- Hosted agents in Foundry Agent Service · Deploy a hosted agent
- Microsoft Teams developer platform
- Declarative agents for Microsoft 365 Copilot
- Model Context Protocol
- GitHub Copilot
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.