Skip to content

Commit dfbceed

Browse files
madiepevmadiepev
committed
Revise lab instructions for clarity and detail across multiple tasks, including updates to agent grounding, setup processes, and task descriptions. Enhance user guidance with additional context and examples for better understanding of the agent's capabilities and deployment as a hosted service.
1 parent d227890 commit dfbceed

8 files changed

Lines changed: 322 additions & 187 deletions

‎Instructions/Consolidated/A-build-and-extend-ai-agents.md‎

Lines changed: 54 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -17,24 +17,57 @@ lab:
1717

1818
# Build and extend AI agents
1919

20-
**Level** ▰▰▰▱▱ **L300** (**L100** beginner → **L500** expert)
20+
**Level** ▰▰▰▱▱ **L300**
2121

22-
An agent becomes genuinely useful when it can *do* things — look up live information,
23-
call your business logic, and act on a user's behalf. In this lab you'll build a
24-
grounded agent and then give it capabilities using **tools**.
22+
(**L100** beginner → **L500** expert)
2523

26-
![Anton](../Media/anton-avatar.png)<br /><strong>Meet Anton, your AI guide.</strong><br />You'll spot **Ask Anton** tips throughout this lab. Want more interactive, hands-on help? Chat with Anton in the *[Ask Anton](https://aka.ms/choose-anton)* app.
24+
Build a practical AI agent with Microsoft Foundry and Python, then extend it with company
25+
knowledge and tools.
2726

28-
<details>
29-
<summary><strong><i>About the Ask Anton app</i></strong></summary>
27+
## The case
3028

31-
<strong><i><a href="https://aka.ms/choose-anton" target="_blank">Ask Anton</a></i></strong> is a generative AI agent that can answer questions about AI concepts and Microsoft Foundry technologies. It's available in two versions at <code>https://aka.ms/choose-anton</code>:
32-
<ul>
33-
<li><strong>Azure-based</strong>: Best experience <i>(requires an Azure subscription and deployment of a model in a Foundry project)</i>.</li>
34-
<li><strong>Browser-based</strong>: Use a small language model in your browser <i>(reduced functionality - may be slow or work only in "basic" mode in older/lower-spec devices)</i>.</li>
35-
</ul>
36-
<blockquote><i>Ask Anton is <u>not</u> a supported Microsoft product or a component of Microsoft Learn or AI Skills Navigator.</i></blockquote>
37-
</details>
29+
You work at **Caldova**, a pharmaceutical manufacturer. Caldova plans to launch a product
30+
sooner than expected, but its three factories can produce about 7% less than the launch
31+
requires.
32+
33+
The planning team must decide whether to move work between Caldova's factories or hire an
34+
approved manufacturing partner, also called a contract manufacturer. You build a supply
35+
chain assistant to help them decide. It uses company policy, analyzes factory output, finds
36+
available production time, estimates partner costs, and checks whether enough materials are
37+
in stock.
38+
39+
## What you'll do
40+
41+
Complete the two core tasks for a working agent, then choose optional tasks based on what
42+
you want to practice.
43+
44+
<!-- BEGIN GENERATED: task-table - do not edit by hand; run: python tools/generate_lab_blocks.py -->
45+
| Section | Task | Level | Time |
46+
| --- | --- | --- | --- |
47+
| **Core** | [Task 1 – Create and ground an agent](A1-create-and-ground-an-agent.md) | ▰▰▱▱▱ L200 | ~15 min |
48+
| **Core** | [Task 2 – Connect a remote MCP server](A2-connect-a-remote-mcp-server.md) | ▰▰▰▱▱ L300 | ~20 min |
49+
| *Optional* | [Task 3 – Call your agent from a client app](A3-call-your-agent-from-a-client-app.md) | ▰▰▰▱▱ L300 | ~20 min |
50+
| *Optional* | [Task 4 – Add custom function tools](A4-add-custom-function-tools.md) | ▰▰▰▱▱ L300 | ~25 min |
51+
| *Optional* | [Task 5 – Capstone: build your own MCP server](A5-capstone-build-your-own-mcp-server.md) | ▰▰▰▰▱ L400 | ~35 min |
52+
| *Optional* | [Task 6 – Promote your assistant to a hosted agent](A6-promote-your-assistant-to-a-hosted-agent.md) | ▰▰▰▱▱ L300 | ~30 min |
53+
54+
**Core tasks:** about **35 minutes**. **Full lab**, including every optional task: about **2 hours 25 minutes**.
55+
<!-- END GENERATED: task-table -->
56+
57+
> **Note**: Some of the technologies used in this exercise are in preview or in active
58+
> development. You may experience some unexpected behavior, warnings, or errors.
59+
60+
Start with [Getting started](A0-getting-started.md) to create your Microsoft Foundry project
61+
and prepare the shared starter code. Each task includes the setup needed to start
62+
independently. If you complete the lab in order, you reuse the same environment and skip
63+
repeated setup.
64+
65+
![Anton](../Media/anton-avatar.png)
66+
67+
**Meet Anton, your AI guide.**
68+
69+
You'll spot **Ask Anton** tips throughout this lab. For more interactive help, use the
70+
*[Ask Anton](https://aka.ms/choose-anton)* app.
3871

3972
<style>
4073
/* "Ask Anton" just-in-time concept blocks */
@@ -58,128 +91,21 @@ details.concept .concept-body { border:1px solid #6b4ba133; border-top:none;
5891

5992
An AI agent is a software service that uses generative AI to understand a request, decide
6093
what to do, and take action on a user's behalf. What makes an agent genuinely useful isn't
61-
the model alone — it's the **knowledge** you ground it in and the **tools** you give it.
94+
the model alone. It also needs relevant **knowledge** and **tools**.
6295

6396
[Learn more →](https://review.learn.microsoft.com/en-us//training/modules/build-extend-ai-agents/1-introduction?branch=pr-en-us-55509)
6497

6598
</div>
6699
</details>
67100

68-
**Your scenario:** you work at **Caldova**, a pharmaceutical manufacturer preparing an
69-
accelerated product launch. Planning forecasts a 7% capacity gap across the three manufacturing
70-
sites, and teams need to know whether they can close it internally or bring in a pre-qualified
71-
contract manufacturer. Across this lab you'll build the supply chain assistant that answers
72-
those questions, adding one capability per task: first grounding it in the company's own supply
73-
chain policy, then connecting it to live documentation, letting it analyze production output,
74-
draft capacity requests, and check material stock.
75-
76-
You'll start with the **Core** tasks that get you to a working, tool-using agent as
77-
quickly as possible. From there, a set of **Optional** tasks lets you go deeper into the
78-
areas that interest you most.
101+
## Is this lab for you?
79102

80-
> **Note**: Some of the technologies used in this exercise are in preview or in active
81-
> development. You may experience some unexpected behavior, warnings, or errors.
82-
83-
## What you'll learn
84-
85-
By completing the **Core** tasks of this exercise, you'll be able to:
86-
87-
- **Create and ground an agent** in the Microsoft Foundry portal so it answers from your
88-
own data rather than guessing.
89-
- **Extend an agent with a tool** by connecting it to a remote **Model Context Protocol
90-
(MCP)** server, and handle tool-approval requests in code.
91-
92-
The **Optional** tasks let you additionally:
93-
94-
- Call your agent from a **client application**.
95-
- Give an agent **custom function tools** that run your own Python logic.
96-
- Build and connect your **own MCP server**.
97-
- Compare two ways to build the same agent: the **Foundry SDK + Responses API** (which you
98-
write) and the **Microsoft Agent Framework** (a provided, ready-to-run variant).
99-
- Deploy your assistant as a **hosted agent** — your own code running in a Foundry-managed
100-
container, invoked by reference just like a prompt agent.
101-
102-
## How this lab is organized
103-
104-
This lab is **modular**. Each task is written to be completed **on its own, starting fresh** —
105-
so you can pick a single task and do just that one. Every task also shares one starter folder,
106-
one virtual environment, and one `.env`, so if you'd rather work straight through, you can.
107-
108-
1. **Start with [Getting started](A0-getting-started.md)** — create your Microsoft Foundry
109-
project (in the portal or with one `azd up` command), get the starter code, and set up
110-
your `.env`. Every task begins from here; if you're doing the whole lab in one sitting, you
111-
only need to do this once.
112-
2. **Do any task.** Each task lists the setup it needs so you can start it independently. If
113-
you're moving straight from the previous task, a short *"Continuing from a previous task?"*
114-
note at the top lets you skip the repeated setup and keep going.
115-
116-
## Lab at a glance
117-
118-
Complete the **Core** tasks first — they end with a working, tool-using agent. Then expand any
119-
**Optional** tasks that interest you.
120-
121-
<!-- BEGIN GENERATED: task-table - do not edit by hand; run: python tools/generate_lab_blocks.py -->
122-
| Section | Task | Level | Time |
123-
| --- | --- | --- | --- |
124-
| **Core** | [Task 1 – Create and ground an agent](A1-create-and-ground-an-agent.md) | ▰▰▱▱▱ L200 | ~15 min |
125-
| **Core** | [Task 2 – Connect a remote MCP server](A2-connect-a-remote-mcp-server.md) | ▰▰▰▱▱ L300 | ~20 min |
126-
| *Optional* | [Task 3 – Call your agent from a client app](A3-call-your-agent-from-a-client-app.md) | ▰▰▰▱▱ L300 | ~20 min |
127-
| *Optional* | [Task 4 – Add custom function tools](A4-add-custom-function-tools.md) | ▰▰▰▱▱ L300 | ~25 min |
128-
| *Optional* | [Task 5 – Capstone: build your own MCP server](A5-capstone-build-your-own-mcp-server.md) | ▰▰▰▰▱ L400 | ~35 min |
129-
| *Optional* | [Task 6 – Promote your assistant to a hosted agent](A6-promote-your-assistant-to-a-hosted-agent.md) | ▰▰▰▱▱ L300 | ~30 min |
130-
131-
**Core tasks:** about **35 minutes**. **Full lab**, including every optional task: about **2 hours 25 minutes**.
132-
<!-- END GENERATED: task-table -->
103+
Choose this lab if you want hands-on practice building an agent with Microsoft Foundry and
104+
Python. You write the agent code, connect remote and custom tools, and work directly with the
105+
tool-calling loop. The web chat interface is provided.
133106

134-
**Choosing your path** — pick the tasks that fit the time you have:
135-
136-
- **Core only (~35 min):** do Tasks 1–2.
137-
- **Core + recommended (~1h 20m):** also do **Task 3** and **Task 4**.
138-
- **Everything (~2h 25m):** add **Task 5** (the capstone builds on Task 4, so do Task 4 first)
139-
and **Task 6** (deploy the assistant as a hosted agent).
140-
141-
> **One assistant, growing capabilities**: Tasks 3–5 all run behind the same provided web
142-
> chat window (`caldova_ui.py`) — the **Caldova Assistant**. You focus only
143-
> on the agent code; each task gives the same assistant a new capability (analyzing output
144-
> data, planning capacity, and checking material stock). You don't edit `caldova_ui.py`; you
145-
> just write a `respond()` function and hand it to `run_chat_app()`.
146-
147-
## Two ways to build the same agent
148-
149-
There's more than one way to write an agent against Microsoft Foundry, and this lab shows you
150-
**two**:
151-
152-
- **The Foundry SDK with the Responses API** — the approach you'll *write* throughout this lab.
153-
You create the agent with `azure-ai-projects`, describe each tool with an explicit JSON
154-
schema, and drive the **tool-calling loop yourself**: read the model's response, run the
155-
tool it asked for, and send the result back. This is deliberately hands-on so you can *see*
156-
the mechanics every agent runtime performs under the hood.
157-
- **The Microsoft Agent Framework (MAF)** — a higher-level framework that hides that plumbing.
158-
You decorate a plain Python function with `@tool` (the schema is generated for you) and call
159-
`await agent.run(...)`, which runs the entire tool-calling loop automatically.
160-
161-
Neither is "more correct" — they're different levels of abstraction. Seeing the raw mechanics
162-
first is what makes the framework's shortcuts meaningful later. To make the contrast concrete,
163-
**Tasks 4 and 5 each ship a ready-to-run MAF edition** of the same assistant
164-
(`functions_agent_maf.py` and `client_maf.py`) that you can read and run alongside your own
165-
version. The Microsoft Agent Framework is covered in depth in **Lab 07 (Agent Framework)** and
166-
**Lab 08 (multi-agent orchestration)**.
167-
168-
## Summary
169-
170-
Across this lab you:
171-
172-
- Created and **grounded** an agent in the Foundry portal so it answers from your data.
173-
- **Extended an agent with a tool** by connecting it to a remote MCP server and handling
174-
tool-approval requests in code.
175-
- (Optionally) consumed an agent from a **client app**, added **custom function tools**,
176-
and built your **own MCP server** — then combined the function tools and your MCP tools
177-
into a single **capstone assistant** that routes each call to the right place.
178-
- (Optionally) promoted the assistant to a **hosted agent** — your own code deployed to a
179-
Foundry-managed container and invoked by reference.
180-
181-
Together these show the two big levers for making agents useful: giving them the right
182-
**knowledge** (grounding) and the right **capabilities** (tools).
107+
Tasks 4 and 5 also include a ready-to-run Microsoft Agent Framework version for comparison.
108+
Task 6 lets you deploy your code as a hosted agent.
183109

184110
## Clean up
185111

‎Instructions/Consolidated/A0-getting-started.md‎

Lines changed: 71 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,18 @@ lab:
1515

1616
# Getting started
1717

18-
This page sets up everything the **Build and extend AI agents** lab needs. **Every task begins
19-
here** — complete this page first. Each task is written so you can then do it on its own; if
20-
you're working through the whole lab in one sitting, you only need to do this setup once.
18+
Prepare the shared cloud resources and local Python environment for the **Build and extend
19+
AI agents** lab. Complete this setup once before starting a task.
2120

22-
**Your scenario:** you work at **Caldova**, a pharmaceutical manufacturer preparing an
23-
accelerated product launch. Across the lab you'll build the supply chain assistant that
24-
powers the business, adding one capability per task.
21+
## The case
22+
23+
**Caldova** is a pharmaceutical manufacturer preparing an early product launch. Its three
24+
factories cannot produce everything the launch requires, so you will build a supply chain
25+
assistant to help the planning team evaluate its options.
26+
27+
Before you add capabilities to the assistant, you need a Microsoft Foundry project, a
28+
deployed model, and the starter code. You reuse this setup throughout the lab, whether you
29+
complete one task or the full sequence.
2530

2631
> **Note**: Some of the technologies used in this lab are in preview or in active
2732
> development. You may experience some unexpected behavior, warnings, or errors.
@@ -36,17 +41,62 @@ Before starting, ensure you have:
3641
- [Git](https://git-scm.com/downloads) installed on your local machine
3742
- Basic familiarity with Python
3843

39-
> \* Python 3.14 isn't supported yet: some dependencies have no 3.14 build. This lab was tested with Python 3.13.12.
44+
> **Note**: Python 3.14 isn't supported yet because some dependencies have no 3.14 build. This lab was tested with Python 3.13.12.
4045
4146
## Create a Microsoft Foundry project
4247

4348
You need a Foundry project and a deployed model for every code task. You can create these
4449
in the portal (the default), or provision them with one command using the Azure Developer
4550
CLI (`azd`).
4651

47-
### Option A — Create the project in the portal (default)
48-
49-
Microsoft Foundry uses projects to organize models, resources, data, and other assets.
52+
<style>
53+
/* "Ask Anton" just-in-time concept blocks */
54+
details.concept { margin:.6rem 0 1rem; }
55+
details.concept > summary { display:inline-block; cursor:pointer; list-style:none;
56+
font-size:.85em; font-weight:600; color:#6b4ba1; background:#6b4ba112;
57+
border:1px solid #6b4ba133; border-radius:999px; padding:.2em .7em; }
58+
details.concept > summary::-webkit-details-marker { display:none; }
59+
details.concept > summary::before { content:"Ask Anton: "; font-weight:700;
60+
padding-left:1.5em;
61+
background:url("../Media/anton-avatar.png") left center / 1.25em 1.25em no-repeat; }
62+
details.concept > summary:hover { background:#6b4ba1; color:#fff; border-color:#6b4ba1; }
63+
details.concept[open] > summary { border-bottom-left-radius:0; border-bottom-right-radius:0; }
64+
details.concept .concept-body { border:1px solid #6b4ba133; border-top:none;
65+
border-radius:0 8px 8px 8px; padding:.6rem .9rem; background:#6b4ba108; font-size:.95em; }
66+
.setup-tabs { display:grid; grid-template-columns:auto auto 1fr; margin:1rem 0; }
67+
.setup-tabs > input { position:absolute; width:1px; height:1px; overflow:hidden;
68+
clip:rect(0 0 0 0); white-space:nowrap; }
69+
.setup-tabs > label { padding:.55rem .9rem; border-bottom:2px solid #d4d4d8;
70+
cursor:pointer; font-weight:600; color:#52525b; }
71+
.setup-tabs > input:focus-visible + label { outline:2px solid #1a45a5; outline-offset:2px; }
72+
.setup-tabs > input:checked + label { color:#1a45a5; border-bottom-color:#1a45a5; }
73+
.setup-tabs .setup-panel { display:none; grid-column:1 / -1; padding-top:.75rem; }
74+
#setup-portal:checked ~ .setup-portal-panel,
75+
#setup-azd:checked ~ .setup-azd-panel { display:block; }
76+
</style>
77+
78+
<details markdown="1" class="concept">
79+
<summary>What is a Microsoft Foundry project?</summary>
80+
<div class="concept-body" markdown="1">
81+
82+
A Microsoft Foundry project is a workspace for building and managing an AI application.
83+
It gives you one place to work with the application's agents, models, tools, and evaluations.
84+
In this lab, the project contains the model deployment and agents used by the Caldova
85+
assistant.
86+
87+
[Learn more →](https://learn.microsoft.com/azure/ai-foundry/what-is-foundry)
88+
89+
</div>
90+
</details>
91+
92+
<div class="setup-tabs">
93+
<input type="radio" name="setup-method" id="setup-portal" checked="checked" />
94+
<label for="setup-portal">Option A: Azure portal</label>
95+
<input type="radio" name="setup-method" id="setup-azd" />
96+
<label for="setup-azd">Option B: Azure Developer CLI</label>
97+
<div class="setup-panel setup-portal-panel" markdown="1">
98+
99+
### Create the project in the portal
50100

51101
1. In a web browser, open the [Foundry portal](https://ai.azure.com) at `https://ai.azure.com` and sign in using your Azure credentials. Close any tips or quick start panes, and if necessary use the **Foundry** logo at the top left to navigate to the home page.
52102

@@ -70,10 +120,13 @@ Microsoft Foundry uses projects to organize models, resources, data, and other a
70120

71121
Keep this browser tab open — you'll use it in Task 1.
72122

73-
### Option B — Provision with azd (optional, one command)
123+
</div>
124+
<div class="setup-panel setup-azd-panel" markdown="1">
74125

75-
If you'd rather not click through the portal, the lab ships an optional `azd` template that
76-
creates the Foundry resource, a project, and a model deployment for you.
126+
### Provision with azd
127+
128+
Choose this option if you prefer to set up the Azure resources from the terminal. The
129+
included `azd` template creates the Foundry resource, project, and model deployment for you.
77130

78131
1. Install the [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd).
79132

@@ -87,11 +140,14 @@ creates the Foundry resource, a project, and a model deployment for you.
87140
1. Answer the prompts (environment name, region). When it finishes, `azd` writes
88141
`PROJECT_ENDPOINT` and `MODEL_DEPLOYMENT_NAME` into `Python/.env` for you.
89142
90-
> **Note**: This provisions the resources but does **not** create the grounded portal
91-
> agent — Task 1 does that. If you're starting at Task 3, run
143+
> **Note**: These commands create the Azure resources, but they don't create the grounded
144+
> agent used in Task 1. If you're starting at Task 3, run
92145
> `python ../setup/bootstrap_agent.py` from the `Python` folder after `azd up` to create
93146
> it. When you're done with the lab, run `azd down` to delete everything it created.
94147
148+
</div>
149+
</div>
150+
95151
## Get the starter code
96152
97153
1. In VS Code, open the Command Palette (**Ctrl+Shift+P**), run **Git: Clone**, and enter:

‎Instructions/Consolidated/A1-create-and-ground-an-agent.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,10 @@ The single most important capability for the Caldova agent is **grounding**.
5353
Grounding attaches trusted source material — such as the supply chain policy document — so the
5454
agent answers *from that data* instead of inventing a response.
5555

56+
You could copy policy details into the agent instructions, but that becomes difficult to
57+
maintain as the policy changes. File search keeps the instructions focused on the agent's
58+
role while the policy remains a separate source that you can replace or update.
59+
5660
[Learn more →](https://review.learn.microsoft.com/en-us/training/modules/build-extend-ai-agents/2-understand-agents-foundry?branch=pr-en-us-55509)
5761

5862
</div>
@@ -65,9 +69,9 @@ agent answers *from that data* instead of inventing a response.
6569
You help planning and materials teams with questions about capacity, contract manufacturers, and materials.
6670
6771
Guidelines:
68-
- Always be clear and concise
72+
- Always be friendly and helpful
6973
- Use the supply chain policy documentation to answer questions accurately
70-
- If you don't know the answer, admit it and suggest contacting the planning desk directly
74+
- If you don't know the answer, admit it and suggest contacting the support team directly
7175
```
7276
7377
1. Download the sample supply chain policy document. Open a new browser tab and navigate to:

0 commit comments

Comments
 (0)