Skip to content

Commit a07408d

Browse files
ttorblettorble
authored
Merge pull request #53585 from ivorb/new-agents
sdk module draft
2 parents ab471bc + fe5a152 commit a07408d

16 files changed

Lines changed: 637 additions & 0 deletions

‎learn-pr/wwl-data-ai/foundry-sdk/01-introduction.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.introduction
3+
title: Introduction
4+
metadata:
5+
title: Introduction
6+
description: Introduction to the Microsoft Foundry SDK.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 1
15+
content: |
16+
[!include[](includes/01-introduction.md)]

‎learn-pr/wwl-data-ai/foundry-sdk/02-chat-playground.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.chat-playground
3+
title: Explore with the Chat playground
4+
metadata:
5+
title: Explore with the Chat playground
6+
description: Learn to use the Chat playground and generate code samples for Microsoft Foundry SDK development.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 7
15+
content: |
16+
[!include[](includes/02-chat-playground.md)]

‎learn-pr/wwl-data-ai/foundry-sdk/03-microsoft-foundry-sdk.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.microsoft-foundry-sdk
3+
title: Understand the Microsoft Foundry SDK
4+
metadata:
5+
title: Understand the Microsoft Foundry SDK
6+
description: Learn about the Microsoft Foundry SDK and its two client types.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 7
15+
content: |
16+
[!include[](includes/03-microsoft-foundry-sdk.md)]

‎learn-pr/wwl-data-ai/foundry-sdk/04-responses-api.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.responses-api
3+
title: Generate responses with the Responses API
4+
metadata:
5+
title: Generate responses with the Responses API
6+
description: Learn to use the Responses API to generate AI responses in applications.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 10
15+
content: |
16+
[!include[](includes/04-responses-api.md)]

‎learn-pr/wwl-data-ai/foundry-sdk/05-exercise.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.exercise
3+
title: Exercise - Use the Microsoft Foundry SDK
4+
metadata:
5+
title: Exercise - Use the Microsoft Foundry SDK
6+
description: Practice using the Microsoft Foundry SDK to build an AI application.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 10
15+
content: |
16+
[!include[](includes/05-exercise.md)]

‎learn-pr/wwl-data-ai/foundry-sdk/06-knowledge-check.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.knowledge-check
3+
title: Knowledge check
4+
metadata:
5+
title: Knowledge check
6+
description: Check your understanding of the Microsoft Foundry SDK.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 5
15+
quiz:
16+
title: Check your knowledge
17+
questions:
18+
- content: What is the primary purpose of the project client in the Microsoft Foundry SDK?
19+
choices:
20+
- content: To generate AI responses using the Responses API
21+
isCorrect: false
22+
explanation: Incorrect. The OpenAI-compatible client is used to generate AI responses.
23+
- content: To access Foundry-native operations like listing connections and managing project properties
24+
isCorrect: true
25+
explanation: Correct. The project client provides access to Foundry-native operations that don't have OpenAI equivalents.
26+
- content: To deploy new AI models to the project
27+
isCorrect: false
28+
explanation: Incorrect. Model deployment is done through the Foundry portal, not the SDK.
29+
- content: Which method do you use to generate responses with the Responses API?
30+
choices:
31+
- content: client.chat.completions.create()
32+
isCorrect: false
33+
explanation: Incorrect. This is the older chat completions API method.
34+
- content: client.responses.create()
35+
isCorrect: true
36+
explanation: Correct. The Responses API uses the responses.create() method.
37+
- content: client.generate.response()
38+
isCorrect: false
39+
explanation: Incorrect. This method doesn't exist in the SDK.
40+
- content: What does the previous_response_id parameter do in the Responses API?
41+
choices:
42+
- content: It links responses together to maintain conversation context
43+
isCorrect: true
44+
explanation: Correct. The previous_response_id parameter maintains conversation context across multiple API calls.
45+
- content: It retrieves an older response from the database
46+
isCorrect: false
47+
explanation: Incorrect. Use the responses.retrieve() method to retrieve previous responses.
48+
- content: It deletes previous responses to save storage space
49+
isCorrect: false
50+
explanation: Incorrect. The parameter doesn't delete responses.
51+
- content: Which package must you install to use the Microsoft Foundry SDK in Python?
52+
choices:
53+
- content: Package `azure-foundry`
54+
isCorrect: false
55+
explanation: Incorrect. This package doesn't exist.
56+
- content: Package `azure-ai-projects`
57+
isCorrect: true
58+
explanation: Correct. The `azure-ai-projects` package provides the Microsoft Foundry SDK for Python.
59+
- content: Package `microsoft-foundry-sdk`
60+
isCorrect: false
61+
explanation: Incorrect. This package doesn't exist.
62+
- content: What advantage does the Responses API offer over traditional chat completions?
63+
choices:
64+
- content: It works only with Azure OpenAI models
65+
isCorrect: false
66+
explanation: Incorrect. The Responses API works with both Azure OpenAI and Foundry direct models.
67+
- content: It provides stateful, multi-turn conversation support
68+
isCorrect: true
69+
explanation: Correct. The Responses API maintains conversation context and provides stateful interactions.
70+
- content: It requires less authentication configuration
71+
isCorrect: false
72+
explanation: Incorrect. Both APIs require the same authentication approach.

‎learn-pr/wwl-data-ai/foundry-sdk/07-summary.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.foundry-sdk.summary
3+
title: Summary
4+
metadata:
5+
title: Summary
6+
description: Summary of the Microsoft Foundry SDK module.
7+
author: ivorb
8+
ms.author: berryivor
9+
ms.date: 02/20/2026
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
ms.collection:
13+
- wwl-ai-copilot
14+
durationInMinutes: 3
15+
content: |
16+
[!include[](includes/07-summary.md)]

‎learn-pr/wwl-data-ai/foundry-sdk/includes/01-introduction.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Developers creating AI solutions with Microsoft Foundry need to work with a combination of services and software frameworks. The Microsoft Foundry SDK brings together common services and code libraries in a project through a central programmatic access point, making it easier for developers to write the code needed to build effective AI apps on Azure.
2+
3+
In this module, you'll learn how to use the Microsoft Foundry SDK to work with resources in a project and generate AI responses.
4+
5+
> [!NOTE]
6+
> Microsoft Foundry SDK is currently in preview. Details described in this module are subject to change.

‎learn-pr/wwl-data-ai/foundry-sdk/includes/02-chat-playground.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
Before you write code with the Microsoft Foundry SDK, it's helpful to explore what your project can do through the Foundry portal. The portal provides interactive tools for testing models and generating code samples that you can use as starting points for your applications.
2+
3+
[ ![Screenshot of the Chat playground in Microsoft Foundry portal.](../media/foundry-playground.png) ](../media/foundry-playground.png#lightbox)
4+
5+
## Exploring with the Chat playground
6+
7+
The **Chat playground** in the Foundry portal provides an interactive environment for testing models before you write any code. You can access it by selecting **Chat playground** from the left navigation.
8+
9+
The playground lets you:
10+
- Send prompts to deployed models and see responses in real time
11+
- Adjust settings like temperature and max tokens
12+
- Add system messages to customize model behavior
13+
- Experiment with different models and configurations
14+
15+
This no-code environment helps you understand how models respond to different inputs and settings, making it easier to design your application.
16+
17+
## Generating code samples
18+
19+
One of the most useful features of the Chat playground is the **Code** button in the chat pane. At any point during your experimentation, you can select this button to see code samples to reproduce a chat session in your app.
20+
21+
The generated code samples include choices for:
22+
- **API** - Using Responses API, or another API like Completions
23+
- **Language** - Select your preferred programming language
24+
- **SDK** - Choose which SDK you want to see a sample of
25+
26+
These samples are pre-populated with your project endpoint, model deployment name, and current settings. They provide a ready-to-use starting point for building your application.
27+
28+
You can copy this code directly into your development environment and modify it to fit your needs.
29+
30+
## From playground to code
31+
32+
The typical workflow for building an AI application with Microsoft Foundry looks like this:
33+
34+
1. **Explore in the playground** - Test prompts, adjust settings, and find what works
35+
2. **Generate code samples** - Use the **Code** tab to get SDK samples
36+
3. **Develop your application** - Take the generated code and customize it for your specific needs
37+
4. **Iterate and refine** - Return to the playground to test new ideas, then update your code
38+
39+
This approach lets you quickly prototype and validate your ideas before investing time in development.
40+
41+
In the next unit, you'll learn about the Microsoft Foundry SDK and how to use it to programmatically work with your projects.

‎learn-pr/wwl-data-ai/foundry-sdk/includes/03-microsoft-foundry-sdk.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
Microsoft Foundry provides a unified approach for building AI applications by connecting to a single project endpoint. The Microsoft Foundry SDK enables developers to work with resources in a Foundry project through language-specific client libraries, making it easier to build AI apps that leverage models, connections, and other resources.
2+
3+
## Understanding the Microsoft Foundry SDK
4+
5+
The Microsoft Foundry SDK provides programmatic access to resources in your projects through a REST API and language-specific client libraries. Available SDKs include:
6+
7+
- [Azure AI Projects for Python](https://pypi.org/project/azure-ai-projects?azure-portal=true)
8+
- [Azure AI Projects for Microsoft .NET](https://www.nuget.org/packages/Azure.AI.Projects?azure-portal=true)
9+
- [Azure AI Projects for JavaScript](https://www.npmjs.com/package/@azure/ai-projects?azure-portal=true)
10+
11+
> [!NOTE]
12+
> This module uses Python code examples for common tasks. You can refer to the language-specific SDK documentation for equivalent code in your preferred language. Each SDK is developed and maintained independently, so some functionality may be at different stages of implementation.
13+
14+
## Installing the SDK
15+
16+
To use the Azure AI Projects library in Python, install the **azure-ai-projects** package from PyPI along with supporting packages:
17+
18+
```bash
19+
pip install azure-ai-projects azure-identity openai
20+
```
21+
22+
## Two client types
23+
24+
The Microsoft Foundry SDK exposes two distinct client types to support different operations:
25+
26+
### Project client
27+
28+
The **project client** (`AIProjectClient`) provides access to Foundry-native operations that don't have OpenAI equivalents. Use the project client to:
29+
30+
- List and retrieve resource connections
31+
- Access project properties and configuration
32+
- Enable application tracing
33+
- Manage datasets and indexes
34+
35+
### OpenAI-compatible client
36+
37+
The **OpenAI-compatible client** handles operations that build on OpenAI concepts and patterns. Use this client for:
38+
39+
- Generating responses with the Responses API
40+
- Working with agents
41+
- Running evaluations
42+
- Fine-tuning models
43+
- Accessing Foundry direct models (non-Azure-OpenAI models)
44+
45+
Most applications use both clients: the project client for setup and configuration, and the OpenAI-compatible client for generating AI responses.
46+
47+
## Connecting to a project
48+
49+
Each Foundry project has a unique endpoint that you can find on the project's **Overview** page in the Foundry portal at [https://ai.azure.com](https://ai.azure.com?azure-portal=true).
50+
51+
The project endpoint follows this format:
52+
53+
```
54+
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
55+
```
56+
57+
Use this endpoint to create an **AIProjectClient** object:
58+
59+
```python
60+
from azure.identity import DefaultAzureCredential
61+
from azure.ai.projects import AIProjectClient
62+
63+
project_endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>"
64+
project_client = AIProjectClient(
65+
credential=DefaultAzureCredential(),
66+
endpoint=project_endpoint
67+
)
68+
```
69+
70+
> [!NOTE]
71+
> The code uses default Azure credentials to authenticate. To enable this authentication, you need to install the **azure-identity** package (shown in the installation command earlier).
72+
73+
> [!TIP]
74+
> To access the project successfully, the code must run in an authenticated Azure session. For example, you can use the Azure CLI `az login` command to sign in before running the code.
75+
76+
## Getting an OpenAI-compatible client
77+
78+
Once you have a project client, you can retrieve an OpenAI-compatible client to work with models and generate responses:
79+
80+
```python
81+
from azure.identity import DefaultAzureCredential
82+
from azure.ai.projects import AIProjectClient
83+
84+
# Connect to the project
85+
project_endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>"
86+
project_client = AIProjectClient(
87+
credential=DefaultAzureCredential(),
88+
endpoint=project_endpoint
89+
)
90+
91+
# Get an OpenAI-compatible client
92+
openai_client = project_client.get_openai_client(api_version="2024-10-21")
93+
```
94+
95+
The OpenAI-compatible client provides access to the Responses API and other OpenAI-style operations, which you'll learn about in subsequent units.

0 commit comments

Comments
 (0)