ai-agents-for-beginners

Mise en place du cours

Introduction

Cette leçon expliquera comment exécuter les exemples de code de ce cours.

Rejoindre les autres apprenants et obtenir de l’aide

Avant de commencer à cloner votre dépôt, rejoignez le canal Discord AI Agents For Beginners pour obtenir de l’aide lors de la configuration, poser des questions sur le cours, ou pour vous connecter avec d’autres apprenants.

Cloner ou forker ce dépôt

Pour commencer, veuillez cloner ou forker le dépôt GitHub. Cela vous permettra d’avoir votre propre version du matériel du cours afin que vous puissiez exécuter, tester et modifier le code !

Cela peut se faire en cliquant sur le lien pour forker le dépôt

Vous devriez maintenant avoir votre propre version forkée de ce cours via le lien suivant :

Dépôt forké

Clone superficiel (recommandé pour atelier / Codespaces)

Le dépôt complet peut être volumineux (~3 Go) si vous téléchargez tout l’historique et tous les fichiers. Si vous assistez seulement à l’atelier ou avez besoin de quelques dossiers de leçons, un clone superficiel (ou un clone sparse) télécharge beaucoup moins.

Clone superficiel rapide — historique minimal, tous fichiers

Remplacez <your-username> dans les commandes ci-dessous par l’URL de votre fork (ou l’URL upstream si vous préférez).

Pour cloner uniquement l’historique du dernier commit (téléchargement léger) :

git clone --depth 1 https://github.com/<your-username>/ai-agents-for-beginners.git

Pour cloner une branche spécifique :

git clone --depth 1 --branch <branch-name> https://github.com/<your-username>/ai-agents-for-beginners.git

Clone partiel (sparse) — blobs minimaux + seulement certains dossiers

Cela utilise le clone partiel et le sparse-checkout (nécessite Git 2.25+ et il est recommandé d’utiliser une version moderne de Git avec support du clone partiel) :

git clone --depth 1 --filter=blob:none --sparse https://github.com/<your-username>/ai-agents-for-beginners.git

Accédez au dossier du dépôt :

cd ai-agents-for-beginners

Ensuite, précisez quels dossiers vous souhaitez (l’exemple ci-dessous montre deux dossiers) :

git sparse-checkout set 00-course-setup 01-intro-to-ai-agents

Après le clonage et la vérification des fichiers, si vous n’avez que besoin des fichiers et souhaitez libérer de l’espace (aucun historique git), veuillez supprimer les métadonnées du dépôt (💀 irréversible — vous perdrez toute la fonctionnalité Git) :

# zsh/bash
rm -rf .git

# PowerShell
Remove-Item -Recurse -Force .git

Utilisation de GitHub Codespaces (recommandé pour éviter les gros téléchargements locaux)

Conseils

Exécuter le code

Ce cours propose une série de notebooks Jupyter que vous pouvez exécuter pour acquérir une expérience pratique de création d’Agents IA.

Les exemples de code utilisent Microsoft Agent Framework (MAF) avec le FoundryChatClient, qui se connecte au Microsoft Foundry Agent Service V2 (l’API Responses) via Microsoft Foundry.

Tous les notebooks Python sont nommés *-python-agent-framework.ipynb.

Prérequis

Un fichier requirements.txt est inclus à la racine de ce dépôt contenant tous les paquets Python requis pour exécuter les exemples de code.

Vous pouvez les installer en exécutant la commande suivante dans votre terminal à la racine du dépôt :

pip install -r requirements.txt

Nous recommandons de créer un environnement virtuel Python pour éviter tout conflit ou problème.

Configuration de VSCode

Assurez-vous que vous utilisez la bonne version de Python dans VSCode.

image

Configurer Microsoft Foundry et Microsoft Foundry Agent Service

Étape 1 : Créer un projet Microsoft Foundry

Vous avez besoin d’un hub Microsoft Foundry et d’un projet avec un modèle déployé pour exécuter les notebooks.

  1. Rendez-vous sur ai.azure.com et connectez-vous avec votre compte Azure.
  2. Créez un hub (ou utilisez un existant). Voir : Aperçu des ressources Hub.
  3. Dans le hub, créez un projet.
  4. Déployez un modèle (par exemple, gpt-5-mini) via Models + Endpoints → Déployer modèle.

Étape 2 : Récupérez l’endpoint de votre projet et le nom du déploiement du modèle

Depuis votre projet dans le portail Microsoft Foundry :

Chaîne de connexion du projet

Étape 3 : Connectez-vous à Azure avec az login

La plupart des notebooks s’authentifient via votre connexion Azure CLI — utilisant AzureCliCredential ou DefaultAzureCredential (qui récupèrent votre session az login) depuis le package azure-identity — ils ne nécessitent donc pas de clés API. Quelques leçons et intégrations optionnelles utilisent des clés API ; vérifiez les prérequis de chaque leçon pour d’éventuelles variables d’environnement additionnelles. Cela nécessite d’être connecté via Azure CLI.

  1. Installez Azure CLI si ce n’est pas déjà fait : aka.ms/installazurecli

  2. Connectez-vous en exécutant :

     az login

    Ou si vous êtes dans un environnement distant/Codespace sans navigateur :

     az login --use-device-code

  3. Sélectionnez votre abonnement si cela est demandé — choisissez celui contenant votre projet Foundry.

  4. Vérifiez que vous êtes connecté :

     az account show

Pourquoi az login ? Les notebooks s’authentifient avec AzureCliCredential (ou DefaultAzureCredential, qui récupère également votre connexion Azure CLI) du package azure-identity. Cela signifie que votre session Azure CLI fournit les identifiants — pas de clés API ou secrets dans votre fichier .env. C’est une bonne pratique de sécurité.

Étape 4 : Créez votre fichier .env

Copiez le fichier exemple :

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

Ouvrez .env et remplissez ces deux valeurs :

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-5-mini
Variable Où la trouver
AZURE_AI_PROJECT_ENDPOINT Portail Foundry → votre projet → page Overview
AZURE_AI_MODEL_DEPLOYMENT_NAME Portail Foundry → Models + Endpoints → nom de votre modèle déployé

C’est tout pour la plupart des leçons ! Les notebooks s’authentifieront automatiquement via votre session az login.

Étape 5 : Installez les dépendances Python

pip install -r requirements.txt

Nous recommandons d’exécuter cela dans l’environnement virtuel que vous avez créé précédemment.

Configuration optionnelle : Azure AI Search (Leçons 5 et 16)

Les notebooks des Leçons 5 (Agentic RAG) et 16 fonctionnent immédiatement avec une base de connaissances en mémoire — aucune ressource Azure supplémentaire requise. Si vous souhaitez les supporter avec un vrai index Azure AI Search, notez que le notebook de la Leçon 16 utilise actuellement une authentification par clé : il passe de la recherche en mémoire à Azure AI Search uniquement lorsque les deux variables AZURE_SEARCH_SERVICE_ENDPOINT et AZURE_SEARCH_API_KEY sont définies ; sinon il continue avec la recherche en mémoire — donc pour l’exécuter avec un vrai index, vous devez aussi définir la clé admin. L’authentification sans clé avec Microsoft Entra ID (RBAC) est la méthode recommandée pour votre propre code en production, conforme au flux az login utilisé partout ailleurs dans ce cours.

Les étapes RBAC ci-dessous s’appliquent aux exemples du guide de configuration et à votre propre code. Elles ne permettent pas l’authentification sans clé dans le notebook de la Leçon 16 ; celle-ci nécessite encore l’endpoint et la clé admin pour utiliser Azure AI Search.

  1. Activez l’accès basé sur les rôles sur votre service de recherche :

     az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey

  2. Attribuez-vous les rôles nécessaires (création/chargement d’index et requêtes) :

     az role assignment create --assignee <your-user-or-principal-id> --role "Search Service Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)
 az role assignment create --assignee <your-user-or-principal-id> --role "Search Index Data Contributor" --scope $(az search service show -g <resource-group> -n <service-name> --query id -o tsv)

  3. Ajoutez l’endpoint à votre fichier .env :

Variable Où la trouver
AZURE_SEARCH_SERVICE_ENDPOINT Portail Azure → votre ressource Azure AI Search → Overview → URL
AZURE_SEARCH_API_KEY Obligatoire (avec l’endpoint) pour activer Azure AI Search dans le notebook de la Leçon 16, qui utilise une authentification par clé. Portail Azure → Paramètres → Clés → clé admin primaire

Pourquoi sans clé ? Les clés administrateur donnent un accès complet en écriture à votre service de recherche et peuvent fuir via les fichiers .env. Avec RBAC, c’est votre identité az login qui est utilisée à la place — le même modèle sans clé Entra ID que les notebooks du cours utilisent (via AzureCliCredential / DefaultAzureCredential). Voir Connexion à Azure AI Search via les rôles.

Voir le guide de configuration Azure AI Search pour des exemples complets de création d’index en Python et .NET.

Configuration supplémentaire pour les leçons qui appellent directement Azure OpenAI (Leçons 6 et 8)

Certains notebooks des leçons 6 et 8 appellent Azure OpenAI directement (via l’API Responses) au lieu de passer par un projet Microsoft Foundry. Ces exemples utilisaient auparavant des modèles GitHub, qui sont obsolètes et ne supportent pas l’API Responses. Ajoutez ces variables dans votre fichier .env :

Variable Où la trouver
AZURE_OPENAI_ENDPOINT Portail Azure → votre ressource Azure OpenAI → Clés et endpoint → Endpoint (ex. https://<votre-ressource>.openai.azure.com)
AZURE_OPENAI_DEPLOYMENT Nom de votre modèle déployé (ex. gpt-5-mini) qui supporte l’API Responses
AZURE_OPENAI_API_KEY Optionnel — uniquement si vous utilisez une authentification par clé au lieu de az login / Entra ID

L’API Responses utilise l’endpoint stable /openai/v1/, donc aucune api-version n’est requise. Connectez-vous avec az login pour utiliser l’authentification sans clé Entra ID.

Fournisseur alternatif : MiniMax (compatible OpenAI)

MiniMax propose des modèles à contexte large (jusqu’à 204K tokens) via une API compatible OpenAI. Comme le OpenAIChatClient du Microsoft Agent Framework fonctionne avec tout endpoint compatible OpenAI, vous pouvez utiliser MiniMax comme alternative de remplacement pour les leçons utilisant OpenAIChatClient.

Ajoutez ces variables dans votre fichier .env :

Variable Où la trouver
MINIMAX_API_KEY MiniMax Platform → Clés API
MINIMAX_BASE_URL Utilisez https://api.minimax.io/v1 (valeur par défaut)
MINIMAX_MODEL_ID Nom du modèle à utiliser (ex. MiniMax-M3)

Exemples de modèles : MiniMax-M3 (recommandé), MiniMax-M2.7, MiniMax-M2.7-highspeed (réponses plus rapides). Les noms et disponibilités des modèles peuvent changer avec le temps, et l’accès à un modèle donné peut dépendre de votre compte.

Les exemples de code utilisant OpenAIChatClient (ex. workflow de réservation hôtel de la leçon 14) détecteront automatiquement et utiliseront votre configuration MiniMax lorsque MINIMAX_API_KEY est défini.

Fournisseur alternatif : Novita AI (compatible OpenAI)

Novita AI fournit une API compatible OpenAI pour les LLM open-source et de pointe (DeepSeek, Llama, Qwen, et plus). Puisque OpenAIChatClient du Microsoft Agent Framework fonctionne avec n’importe quel point de terminaison compatible OpenAI, vous pouvez utiliser Novita AI comme une alternative prête à l’emploi à Azure OpenAI ou OpenAI.

Ajoutez ces variables à votre fichier .env :

Variable Où la trouver
NOVITA_API_KEY Tableau de bord Novita AI → Clés API
NOVITA_BASE_URL Utilisez https://api.novita.ai/openai/v1 (valeur par défaut)
NOVITA_MODEL_ID Nom du modèle à utiliser (ex. : moonshotai/kimi-k3)

Exemples de modèles : moonshotai/kimi-k3, zai-org/glm-5.2, deepseek/deepseek-v4-flash-0731. Novita AI héberge également de nombreuses autres familles de modèles open-source (Llama, Qwen, GLM, et plus) — consultez la bibliothèque de modèles Novita AI pour la liste actuelle des modèles disponibles et leurs identifiants.

Les exemples actuels ne consomment pas automatiquement les variables NOVITA_*. Pour utiliser Novita AI, transmettez explicitement ces valeurs lors de la construction de OpenAIChatClient dans l’exemple que vous exécutez.

Fournisseur alternatif : Foundry Local (Exécutez des modèles sur votre appareil)

Foundry Local est un runtime léger qui télécharge, gère et sert les modèles de langue entièrement sur votre propre machine via une API compatible OpenAI — sans besoin de cloud.

Comme le OpenAIChatClient du Microsoft Agent Framework fonctionne avec tout endpoint compatible OpenAI, Foundry Local est une alternative locale prête à l’emploi à Azure OpenAI.

1. Installez Foundry Local

# Windows
winget install Microsoft.FoundryLocal

# macOS
brew install foundrylocal

2. Téléchargez et lancez un modèle (cela démarre aussi le service local) :

foundry model list          # voir les modèles disponibles
foundry model run phi-4-mini

3. Installez le SDK Python utilisé pour découvrir le point de terminaison local :

pip install foundry-local-sdk

4. Configurez le Microsoft Agent Framework sur votre modèle local :

from foundry_local import FoundryLocalManager
from agent_framework.openai import OpenAIChatClient

# Télécharge (si nécessaire) et sert le modèle localement, puis découvre le point de terminaison/port.
manager = FoundryLocalManager("phi-4-mini")

chat_client = OpenAIChatClient(
    base_url=manager.endpoint,      # par exemple http://localhost:<port>/v1
    api_key=manager.api_key,        # toujours "non requis" pour Foundry Local
    model_id=manager.get_model_info("phi-4-mini").id,
)

agent = chat_client.as_agent(
    name="LocalAgent",
    instructions="You are a helpful assistant running fully on-device.",
)

Remarque : Foundry Local expose un point de terminaison Chat Completions compatible OpenAI. Utilisez-le pour le développement local et les scénarios hors ligne. Pour l’ensemble des fonctionnalités de l’API Réponses (conversations avec état, etc.), utilisez Azure OpenAI ou un projet Microsoft Foundry.

Configuration supplémentaire pour la Leçon 8 (Workflow de Grounding Bing)

Le notebook du workflow conditionnel dans la leçon 8 utilise le grounding Bing via Microsoft Foundry. Si vous prévoyez d’exécuter cet exemple, ajoutez cette variable à votre fichier .env :

Variable Où la trouver
BING_CONNECTION_ID Portail Microsoft Foundry → votre projet → Gestion → Ressources connectées → votre connexion Bing → copiez l’ID de connexion

Dépannage

Erreurs de vérification de certificat SSL sur macOS

Si vous êtes sur macOS et rencontrez une erreur telle que :

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain

Il s’agit d’un problème connu avec Python sur macOS où les certificats SSL du système ne sont pas automatiquement reconnus comme fiables. Essayez les solutions suivantes dans l’ordre :

Option 1 : Exécutez le script Install Certificates de Python (recommandé)

# Remplacez 3.XX par votre version Python installée (par exemple, 3.12 ou 3.13) :
/Applications/Python\ 3.XX/Install\ Certificates.command

Option 2 : Utilisez connection_verify=False dans votre notebook (uniquement pour les notebooks GitHub Models)

Dans le notebook de la Leçon 6 (06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb), une solution de contournement commentée est déjà incluse. Décommentez connection_verify=False si vous rencontrez des erreurs de certificat :

client = ChatCompletionsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(token),
    connection_verify=False,  # Désactiver la vérification SSL si vous rencontrez des erreurs de certificat
)

⚠️ Attention : Désactiver la vérification SSL (connection_verify=False) réduit la sécurité en sautant la validation du certificat. N’utilisez ceci que temporairement en environnement de développement. Ne jamais l’utiliser en production.

Option 3 : Installez et utilisez truststore

pip install truststore

Ensuite, ajoutez ce qui suit en haut de votre notebook ou script avant tout appel réseau :

import truststore
truststore.inject_into_ssl()

Bloqué quelque part ?

Si vous rencontrez des problèmes avec cette configuration, rejoignez notre Azure AI Community Discord ou créez une issue.

Leçon suivante

Vous êtes maintenant prêt à exécuter le code de ce cours. Bon apprentissage dans l’univers des agents IA !

Introduction aux agents IA et cas d’utilisation d’agents

Avertissement : Ce document a été traduit à l’aide du service de traduction automatique Co-op Translator. Bien que nous nous efforçions d’assurer l’exactitude, veuillez noter que les traductions automatisées peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue native doit être considéré comme la source faisant autorité. Pour les informations critiques, il est recommandé de recourir à une traduction professionnelle réalisée par un humain. Nous ne saurions être tenus responsables des malentendus ou erreurs d’interprétation découlant de l’utilisation de cette traduction.

This site is open source. Improve this page.