Microsoft Foundry · hands-on workshop
Agents that act
Build, ground, equip, evaluate and govern AI agents
Hands-on workshop In your own Azure subscription
Vraja Kishore Mudumbai Microsoft
Theme for the day: agents that act, not agents that answer. By the end, everyone has built agents in their own subscription that read live data, decide, call tools and run together as a hosted agent. Press S for speaker view.
Today: three hours, eight sessions
1 0:00 · 50 min Foundry walkthrough Models, agents, tools, guardrails + showcase demos
2 0:50 · 20 min Project and model Verify your project and model; compare models
3 1:10 · 25 min Build the first agent Anomaly + diagnosis agents with a function tool
4 1:45 · 15 min Knowledge and actions Demo: Foundry IQ citations, work-order tool, approval step
5 2:00 · 20 min Trace and evaluate App Insights traces; coherence and fluency evaluation
6 2:20 · 20 min Orchestrate and deploy Multi-agent orchestration in code, deployed as a hosted agent
7 2:40 · 10 min Production readiness Identity, RBAC, network, safety, monitoring
8 2:50 · 10 min Next steps Pick one use case, name one owner
☕ Break 1:35–1:45, after session 3
The agenda. Sessions 1 and 4 are portal walkthroughs and demos. Sessions 2, 3, 5 and 6 are hands-on in your own project. Sessions 7 and 8 are discussion.
Before we start: is your subscription ready?
Two kinds of permission. Most first-day failures are the second one.
Contributor
Control plane: create things
Foundry resource and project Model deployment Application Insights, Log Analytics
Foundry Project Manager
Data plane: use things
Create and version agents Run conversations and tools Run evaluations Deploy hosted agents
Owner or Contributor alone can't build agents. Ask an Owner or User Access Administrator to grant Foundry Project Manager on your resource group.
Region and quota ≥ 10K TPM of gpt-5.4 per person; gpt-5-mini as fallback
Workstation Codespaces, or Python 3.10+, Azure CLI 2.80+, azd 1.27.1+, Git
Network ai.azure.com, *.services.ai.azure.com, GitHub, PyPI
Provisioned Your own project (<alias>-workshop), model, App Insights
Smoke test Playground replies; smoke_test.py passes
Full checklist: PREREQUISITES.md · RBAC for Foundry
If you see PermissionDenied while creating an agent, the Foundry Project Manager role is usually missing. Role assignments can take up to 10 minutes to apply; sign out and in again. Everyone shares the resource group but not the project: use only your own project, named with your alias. The labs create agents with fixed names, so two people in one project overwrite each other's agents.
Part 1 of 4
The platform
One platform, from model to production agent
The platform See it act Build it Ship it
A tour of the Foundry portal, following the agent lifecycle from left to right.
From a chatbot that answers to an agent that acts
📡
Live data Reads the system, not just a document
Chatbot: answers from a PDF you uploaded
Agent: calls tools for current sensor and ERP data
🧮
Computes Numbers come from code, not memory
Chatbot: guesses plausible numbers
Agent: runs Python and threshold checks to get them
🛠️
Acts With a human gate where it matters
Chatbot: stops at a suggestion
Agent: raises the work order after a supervisor approves
🔍
Accountable You can see and score every step
Chatbot: no record of why it answered
Agent: every tool call is traced and evaluated
Grounding in documents appears once, using Foundry IQ. The main pattern is agents that read sensor data, decide and trigger an action, with a human approval step.
Microsoft Foundry, left to right
🧠
Models Catalog, compare, route
🤖
Agents Prompt, voice, hosted
🛠️
Tools Functions, MCP, OpenAPI
📚
Knowledge Foundry IQ, memory
🔀
Orchestration Agent Framework, in code
📈
Observe Traces, evaluations, monitoring
🛡️
Operate Identity, RBAC, network, cost
📣 Publish to Microsoft Teams and Microsoft 365 Copilot, so adoption isn't another app.
Use the new Foundry portal (ai.azure.com, New Foundry on) with a Foundry project . Hub-based projects don't get the new agent capabilities or Foundry IQ.
The portal click path for the walkthrough. Everything shown is in the new Foundry portal.
Models: a dropdown, not a rewrite
"Is CP-003 above its vibration limit?"
"Summarise last shift's alarms"
"Why do MX-001 and EX-002 drift together after maintenance?"
→
Model Router One deployment. Routes each request to the most cost-effective model that meets the quality bar.
→
Small, fast lookup
General purpose summary
Reasoning root cause
OpenAI GPT-5.x Anthropic Claude xAI Grok DeepSeek Meta Llama Microsoft MAI Phi
Global Standard · Data Zone · Standard
Check the retirement date on every model card
Routing shown is illustrative. Pay for reasoning only when the question needs it.
Model cards show each model's retirement date, so model choice is worth revisiting regularly. You can compare the same prompt on two models side by side, and Model Router picks a model for each request.
Three ways to build an agent, one runtime
📝
Prompt agent Instructions + model + tools, defined as configuration. Built in the portal or with the SDK. Every save is a new version , and Foundry runs it for you.
Lab: anomaly + diagnosis agents
🎙️
Voice agent Preview Real-time speech through Voice Live, with the same tools as a text agent. Telephony and Teams channels.
Demo: a technician speaks in their own language
📦
Hosted agent Your code and framework (Microsoft Agent Framework, LangGraph and others) in a container, with a managed endpoint, scaling and identity.
Lab: the multi-agent orchestration, deployed with azd ai agent
Start with a prompt agent. Move to hosted only when you need custom orchestration.
A prompt agent has instructions, a model, tools and versions. Versions matter later for evaluations and rollback. Hosted agents are the path for running your own agent code.
Your first agent, in code
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
agent = project.agents.create_version(
agent_name="fault-diagnosis",
definition=PromptAgentDefinition(
model="gpt-5.4",
instructions="You diagnose faults on tyre-plant machines.",
tools=[CodeInterpreterTool()],
),
)
response = openai.responses.create(
input="CP-003 vibration is 2x baseline. Likely cause?",
extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)
1 Connect to the project with Microsoft Entra ID. No keys.
2 Define the agent: model, instructions, tools. Each call creates a new version.
3 Call it through the Responses API by name.
✓ The same agent shows up in the portal, the playground, traces and evaluations.
📎 Quickstart: create a prompt agent · package azure-ai-projects 2.x
This is the pattern used throughout the lab. DefaultAzureCredential means no API keys anywhere. The lab's agents.py uses the same pattern with a check_thresholds function tool.
Tools: how agents do things
Integrating SAP PM, Maximo, a DMS or a TMS is configuration plus an API , not a new platform.
Tools turn an agent from an answerer into an actor. Toolboxes let one team own the integrations and govern what agents are allowed to do.
Acting safely: a tool call that waits for approval
tool = MCPTool(
server_label="cmms",
server_url="https://<your-cmms-mcp-endpoint>/mcp",
require_approval="always",
project_connection_id="cmms-connection",
)
# ...create the agent with tools=[tool], then call it...
approvals = []
for item in response.output:
if item.type == "mcp_approval_request" and item.id:
ok = supervisor_approves(item.name, item.arguments)
approvals.append(McpApprovalResponse(
type="mcp_approval_response",
approve=ok,
approval_request_id=item.id,
))
response = openai.responses.create(
input=approvals,
previous_response_id=response.id,
extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
1 The agent decides a work order is needed and proposes the tool call.
2 Execution pauses : tool name and arguments go to a person, in your UI or a Teams card.
3 Approved: the tool runs. Rejected: the agent explains and stops.
⏱ Every request and decision is in the trace.
📎 Connect an agent to an MCP server · supervisor_approves is your own approval UX
This is the code behind a human approval before a tool runs. In lab block C, Agent Framework does the same with approval_mode="always_require" on the work-order tool. Nothing is written to the maintenance system until a supervisor approves.
Knowledge and memory, as managed services
📁 SharePoint (user permissions enforced)
🗄️ Blob storage: manuals, SOPs
🏞️ OneLake
🌐 Web
→
📚 Foundry IQ knowledge base
Plans subqueries from the question Keyword, vector or hybrid search per source Semantic reranking Returns answers with source references low medium high reasoning effort
→MCP
🤖 Diagnosis agent "Likely bearing wear on CP-003. Replace per SOP 4.2."
📎 CP-003 maintenance manual, section 4.2
Memory Preview
Session: the current conversation
User: this technician's preferences and history
Procedural: how this plant does things
📎 Connect a Foundry IQ knowledge base · needs Azure AI Search (Basic or higher)
Chatting with documents is one tool among many. In the session 4 demo, a knowledge base built from a machine manual is attached to the diagnosis agent, and its answer includes a citation. Reasoning effort trades latency and cost for better retrieval.
Part 2 of 4
See it act
Orchestration, demos and observability
The platform See it act Build it Ship it
Part 2: orchestration, demos and observability.
A multi-agent orchestration with a human gate
anomaly
no anomaly
📡 Sensor feed 5 machines, 4 signals 🤖 Anomaly agent check_thresholds() 🤖 Diagnosis agent root cause + Foundry IQ 🙋 Supervisor approve / reject 🛠️ Work order CMMS tool call 📝 Log to shift report
Agents as steps Each agent has its own tools and is evaluated on its own.
Approval step Nothing reaches the CMMS until a person says yes.
Code first, hosted Agent Framework, deployed as a hosted agent. Visual option: Logic Apps.
The session 4 demo, built with Microsoft Agent Framework and running as a hosted agent. In lab block C you build it yourself, including the approval step. The approval step is where trust is built.
Showcase: agents doing the work
🏭
Agents on live machine data Anomaly → diagnosis → approval → work order, on the factory scenario
6 min
🖱️
Browser automation Preview Looks up part specs on supplier portals that have no API
5 min
🐍
Code Interpreter as analyst Plots vibration against RPM for 48 h and checks for a bearing signature
4 min
🎙️
Voice agent Preview A technician or service agent speaks in their own language and gets a diagnosis by voice
5 min
🧪
Evaluate, red-team, monitor "Is it safe to put in front of thousands of users?"
4 min
💻
Foundry Toolkit for VS Code Developer audiences: the orchestration in Agent Inspector → hosted agent with azd ai agent
optional
A selection of demos of agents doing real work. Browser automation and voice are in preview.
You can't ship what you can't see
Traces invoke_agent fault-diagnosis 4.1s
├─ chat gpt-5.4 2.3s
├─ execute_tool check_thresholds
└─ mcp knowledge-base 0.9s Every run, tool call, token count and latency, in Application Insights.
Evaluations groundedness 4.6 / 5
relevance 4.4 / 5
task_adherence pass 92%
content_safety 0 flagged Score a test set before every change. Generate synthetic data from the agent's instructions Preview .
Monitoring runs (1h) 1,240
p95 latency 6.8s
tokens / run 3.2K
quality alerts 1 Agent monitoring dashboard: live quality, latency and cost over recent traces.
Sample values are illustrative.
Shows a completed evaluation run on the diagnosis agent, the red-teaming view, and the monitoring dashboard over recent traces.
Part 3 of 4
Build it
Hands-on lab in your own subscription, about 100 minutes
The platform See it act Build it Ship it
The lab code is in the factory folder of this workshop's repository. You completed Challenge 0 in the prerequisites; in the room you only verify it.
Lab scenario: TireForge Industries
A tyre plant with five critical machines, each streaming temperature, pressure, vibration and RPM.
🔥 CP-003
Curing press
temp 171°C vib 5.9 ▲ press 15.2
Detect Compare readings against each machine's thresholds
Diagnose Reason about the likely root cause and recommend an action
Report Produce a consolidated factory health summary
Readings are illustrative. The same pattern applies to connected-product diagnostics and supply-chain exceptions. 📎 Lab guide
The check_thresholds tool grounds the anomaly agent in real machine specs rather than the model's general knowledge of what "normal" vibration looks like.
What you'll build
A Set up + first agents 45 min · sessions 2–3
Verify project, model and .env Compare two models in the catalog Run agents.py: anomaly and diagnosis agents with check_thresholds Edit instructions → new agent version B Knowledge + actions 15 min · session 4 · demo
Foundry IQ knowledge base from a machine manual Answer with a citation Work-order tool through MCP or OpenAPI Approval step before the tool runs C Observe, evaluate, orchestrate 40 min · sessions 5–6
Run monitor.py; open a trace: tool call, tokens, latency Run an evaluation: coherence and fluency Run the orchestration and approve a work order: run_local.py Deploy it as a hosted agent: azd deploy
Quota error? Switch to gpt-5-mini. Blocked? Pair with a neighbour or use Codespaces.
Block A is lab Challenge 1. Block B is a demo. Block C is Challenges 2 to 4. In the evaluation challenge, don't enable Tool Call Accuracy for local-only tools.
Success: a working agent system, in your subscription
Everyone leaves with all seven, and keeps them.
🔀
Orchestration
hosted agent
If you get blocked, raise your hand early. Most fixes take one minute: a role, a region, or a quota.
The goal for the lab: all seven pieces working in your own subscription.
If you get stuck
You see Likely cause Fix
PermissionDenied creating an agentMissing Foundry Project Manager role Admin assigns it on the resource group; wait up to 10 minutes; sign in again InsufficientQuotaNo Global Standard quota in this region Use gpt-5-mini, another region, or request quota DeploymentModelNotSupportedModel or version not offered in this region az cognitiveservices model list --location <region>RequestDisallowedByPolicyAzure Policy deny (region, network, tags) Exempt the sandbox resource group, or add the required tags DefaultAzureCredential failedWrong tenant or not signed in az login --tenant <id>, then az account setCan't run az login Sign-in blocked FOUNDRY_API_KEY in .env + portal stepsazd uses the wrong accountazd has its own sign-inazd config set auth.useAzCliAuth true'project' is misspelledAzure CLI older than 2.80 az upgradeAgents or traces you didn't create In a colleague's project Switch to your own project Classic or hub screens New Foundry toggle is off Turn on New Foundry in the portal header
PREREQUISITES.md in the workshop repository has the same troubleshooting table.
Part 4 of 4
Ship it
Production readiness, and what to build next
The platform See it act Build it Ship it
Part 4: security and production readiness, shown in the Foundry portal.
Governance is in the platform, not a policy PDF
Control Where it lives in Foundry Check before you publish
🪪 Entra identity Agent identity (Entra Agent ID); project managed identity One identity per agent 👥 RBAC Foundry User · Project Manager · Owner · Account Owner Least privilege on project and tools 🔑 Managed identity Project identity for AI Search, Storage and tools No keys in code 🌐 Network and data Private endpoints, BYO VNet, Data Zone deployments, BYO storage Standard setup for production 🛡️ Content safety Deployment content filters; agent guardrails; red teaming Filters on, red-team run done 📈 Monitoring Tracing, monitoring dashboard, cost per project, retirement dates Alerts + model-upgrade plan
Gate every release on an evaluation run , the same way you gate code on tests.
The controls in order: Entra identity, RBAC, managed identity, network and data controls, content safety, monitoring.
Workshop setup vs production setup
Basic setup Workshop
🤖 Foundry Agent Service
Microsoft-managed storage
Standard setup Production
🤖 Foundry Agent Service
Your Cosmos DBconversations
Your Storagefiles
Your AI Searchvectors
Optional: your VNet (private networking) · customer-managed keys
📎 Agent environment setup: basic vs standard
The workshop uses basic setup on purpose. For a pilot that touches real plant or customer data, move to standard setup so conversations, files and vectors live in your own resources.
Brainstorm
Agent patterns you can pilot next
🛠️ Maintenance copilot
Sensor feed → Diagnosis agent + Manuals → Approval → CMMS work order
Pilot: 2 critical lines, 4 weeks of history
📡 Connected-product diagnostics
Telemetry → Diagnosis agents + Manuals → Book service
Pilot: 50 units, one product family
🎙️ Service and warranty desk
Voice or chat agent + Policy KB + user memory → Entitlement tool → Escalate
Pilot: one product line, 5 intents
🚚 Supply-chain control tower
Shipments + inventory → Exception agent → Approval → Teams
Pilot: one lane, late shipments
🧾 Document to ERP
Extract → Validation agent → Approve mismatches → ERP
Pilot: 200 historical documents
📐 Engineering knowledge
SharePoint (Foundry IQ) → Q&A agent → Teams
Pilot: 2 libraries, 20 engineers
Which pattern matches your top business problem, and which would you pilot first?
Brainstorm
Shape your first pilot, together
Use case Which business problem, for which users?
Owner One named person on the business side
Data sample What data, how much, and is it approved for a pilot?
Systems and tools Which APIs or MCP servers does the agent call?
Human gate Which actions need an approval, and from whom?
Success measure The one number that shows it worked
Evaluation gate Test set and minimum scores before anyone outside the pilot sees it
Fill this in together for one use case.
Pick one use case. Name one owner. Two weeks.
Today Choose the use case and the owner; confirm the subscription and region
Week 1 Data sample and tools wired; first agent version; baseline evaluation
Week 2 Orchestration with approval, as a hosted agent; evaluation gate; demo to the business sponsor
Then Fortnightly solutioning cadence + Foundry Toolkit enablement for developers
🧰 Toolboxes one team owns integrations
🪪 Entra Agent ID every agent has an identity
📣 Publish to Teams adoption isn't another app
Recap of what each person built: project → model → agents with a function tool → trace → evaluation → hosted multi-agent orchestration.
Keep going
Resources to keep going. Also see the Learn path "Develop AI agents with Microsoft Foundry and VS Code".
Let's build.
ai.azure.com → your project → Build → Agents
Vraja Kishore Mudumbai Microsoft
Time to build: open your project in the Foundry portal and start lab block A.