原文出处：Course Setup 原作者：Microsoft · 许可证：MIT License 中文译本由诸葛AI学院整理，仅供学习参考，版权归原作者与微软所有。

课程准备

简介

本课讲解如何运行本课程的代码示例。

加入其他学习者并获得帮助

在开始克隆仓库之前，先加入 AI Agents For Beginners 的 Discord 频道，配置上遇到问题、对课程有疑问，或想和其他学习者交流，都可以在这里进行。

克隆或复刻本仓库

第一步，请克隆（clone）或复刻（fork）这个 GitHub 仓库。这样你会得到一份属于自己的课程材料，可以运行、测试和修改代码！

操作方法是点击复刻仓库的链接。

此时你应该已经在下面的链接中拥有了本课程的专属复刻版本。

浅克隆（推荐用于工作坊 / Codespaces）

如果把完整历史和所有文件都下载下来，整个仓库会很大（约 3 GB）。如果你只是参加工作坊，或者只需要其中几个课程文件夹，浅克隆（shallow clone）或稀疏克隆（sparse clone）下载的内容要少得多。

快速浅克隆 —— 最小历史，全部文件

把下面命令里的 <your-username> 换成你的复刻地址（如果你更愿意用上游地址也可以）。

只克隆最近一次提交的历史（下载量小）：

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

克隆指定分支：

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

部分（稀疏）克隆 —— 最少 blob + 只取选中的文件夹

这里用到部分克隆（partial clone）和 sparse-checkout（需要 Git 2.25 以上，并推荐使用支持部分克隆的较新版本 Git）：

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

进入仓库目录：

bash cd ai-agents-for-beginners

然后指定你要的文件夹（下面的例子选中两个文件夹）：

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

克隆完成并确认文件无误后，如果你只需要文件本身、想释放磁盘空间（不再保留 git 历史），可以删除仓库元数据（💀 不可逆 —— 你会失去全部 Git 功能）：

```bash

zsh/bash

rm -rf .git ```

```powershell

PowerShell

Remove-Item -Recurse -Force .git ```

使用 GitHub Codespaces（推荐，可避免本地大量下载）

• 通过 GitHub 界面 为本仓库新建一个 Codespace。
• 在新建 Codespace 的终端里，运行上面任意一条浅克隆 / 稀疏克隆命令，只把需要的课程文件夹拉进 Codespace 工作区。
• 可选：在 Codespaces 内完成克隆后，删除 .git 以回收额外空间（见上面的删除命令）。
• 注意：如果你希望直接在 Codespaces 里打开仓库（不做额外克隆），请注意 Codespaces 会构建 devcontainer 环境，仍可能准备好比你实际需要更多的资源。

小提示

• 只要你想编辑和提交，就把克隆地址换成你自己的复刻地址。
• 如果之后需要更多历史或文件，可以用 fetch 补齐，或者调整 sparse-checkout 以包含更多文件夹。

运行代码

本课程提供一系列 Jupyter Notebook，你可以运行它们，动手体验构建 AI 智能体（agent）。

代码示例使用 Microsoft Agent Framework（MAF） 配合 FoundryChatClient，通过 Microsoft Foundry 连接 Microsoft Foundry Agent Service V2（即 Responses API）。

所有 Python notebook 都标注为 *-python-agent-framework.ipynb。

环境要求

• Python 3.12+

• 注意：如果还没装 Python 3.12，请先安装它，然后用 python3.12 创建 venv，以确保按 requirements.txt 装上正确版本。

  示例

  创建 Python venv 目录：

  bash python -m venv venv

  然后激活 venv 环境：

  ```bash

  zsh/bash

  source venv/bin/activate ```

  ```dos

  Windows 命令提示符

  venv\Scripts\activate ```

• .NET 10+：使用 .NET 的示例代码，请确保安装 .NET 10 SDK 或更高版本。然后检查已安装的 .NET SDK 版本：

  bash dotnet --list-sdks

• Azure CLI —— 身份验证必需。从 aka.ms/installazurecli 安装。

• Azure 订阅 —— 用于访问 Microsoft Foundry 和 Microsoft Foundry Agent Service。
• Microsoft Foundry 项目 —— 一个已经部署了模型的项目（例如 gpt-5-mini）。见下文第 1 步。

我们在仓库根目录放了一个 requirements.txt 文件，里面包含运行代码示例所需的全部 Python 包。

在仓库根目录打开终端，运行以下命令即可安装：

bash pip install -r requirements.txt

我们建议创建 Python 虚拟环境，以避免冲突和各种问题。

配置 VSCode

请确认 VSCode 中使用的是正确版本的 Python。

配置 Microsoft Foundry 与 Microsoft Foundry Agent Service

第 1 步：创建 Microsoft Foundry 项目

要运行这些 notebook，你需要一个 Microsoft Foundry 的 hub（中心） 和 project（项目），并在其中部署模型。

1. 打开 ai.azure.com，用你的 Azure 账号登录。
2. 创建一个 hub（也可以使用已有的）。参见：Hub 资源概览。
3. 在这个 hub 内创建一个 project。
4. 从 Models + Endpoints（模型与终结点） → Deploy model（部署模型） 部署一个模型（例如 gpt-5-mini）。

第 2 步：获取项目终结点与模型部署名

在 Microsoft Foundry 门户中打开你的项目：

• Project Endpoint（项目终结点） —— 进入 Overview（概览） 页面，复制终结点 URL。

• Model Deployment Name（模型部署名） —— 进入 Models + Endpoints，选中你已部署的模型，记下 Deployment name（部署名）（例如 gpt-5-mini）。

第 3 步：用 az login 登录 Azure

大多数 notebook 通过你的 Azure CLI 登录状态完成身份验证 —— 使用 azure-identity 包里的 AzureCliCredential 或 DefaultAzureCredential（两者都会读取你的 az login 会话），因此不需要 API 密钥（key）。少数课程和可选集成会用到 API 密钥；请查看各课程的前置条件，了解是否需要额外的环境变量（environment variable）。这要求你先通过 Azure CLI 登录。

1. 如果还没安装，安装 Azure CLI：aka.ms/installazurecli

2. 运行以下命令登录：

   bash az login

   如果你在没有浏览器的远程环境 / Codespace 里：

   bash az login --use-device-code

3. 如果被提示，选择你的订阅 —— 选择包含你 Foundry 项目的那个。

4. 确认已登录：

   bash az account show

为什么用 az login？ notebook 使用 azure-identity 包中的 AzureCliCredential（或 DefaultAzureCredential，它同样会读取你的 Azure CLI 登录状态）进行身份验证。也就是说，凭据由你的 Azure CLI 会话提供 —— .env 文件里不需要任何 API 密钥或机密。这是一种安全最佳实践。

第 4 步：创建你的 .env 文件

复制示例文件：

```bash

zsh/bash

cp .env.example .env ```

```powershell

PowerShell

Copy-Item .env.example .env ```

打开 .env，填入下面两个值：

env AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id> AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-5-mini

对大多数课程来说，这就够了！notebook 会通过你的 az login 会话自动完成身份验证。

第 5 步：安装 Python 依赖

bash pip install -r requirements.txt

我们建议在你前面创建的虚拟环境里运行这条命令。

可选配置：Azure AI Search（第 5 课与第 16 课）

第 5 课（Agentic RAG）和第 16 课的 notebook 开箱即用，使用内存知识库 —— 不需要额外的 Azure 资源。如果你想用真实的 Azure AI Search 索引作为后端，请注意 第 16 课的 notebook 目前使用基于密钥的身份验证：只有当 AZURE_SEARCH_SERVICE_ENDPOINT 和 AZURE_SEARCH_API_KEY 两者都设置时，它才会从内存搜索切换到 Azure AI Search，否则一直留在内存搜索 —— 所以要让它针对真实索引运行，你必须同时设置管理员密钥。对你自己的生产代码，推荐使用 Microsoft Entra ID（RBAC）的无密钥身份验证，这也和本课程其他地方使用的 az login 流程一致。

下面的 RBAC 步骤适用于配置指南中的示例和你自己的代码。它们不会让第 16 课的 notebook 变成无密钥身份验证；第 16 课要使用 Azure AI Search，仍然需要同时提供终结点和管理员密钥。

1. 在你的搜索服务上启用基于角色的访问：

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

2. 为自己分配所需角色（创建 / 加载索引以及查询）：

   bash 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. 把终结点添加进你的 .env 文件：

为什么用无密钥？ 管理员密钥对你的搜索服务拥有完整写权限，并且可能通过 .env 文件泄露。改用 RBAC 后，使用的是你 az login 的身份 —— 与课程 notebook 使用的无密钥 Entra ID 模式一致（通过 AzureCliCredential / DefaultAzureCredential）。参见使用角色连接 Azure AI Search。

Python 和 .NET 完整的索引创建示例，见 Azure AI Search 配置指南。

直接调用 Azure OpenAI 的课程需要额外配置（第 6 课与第 8 课）

第 6 课和第 8 课的部分 notebook 直接调用 Azure OpenAI（使用 Responses API），而不是经过 Microsoft Foundry 项目。这些示例原先使用 GitHub Models，而该服务已被弃用、不支持 Responses API。请把这些变量添加进你的 .env 文件：

Responses API 使用稳定的 /openai/v1/ 终结点，因此不需要 api-version。用 az login 登录即可使用无密钥的 Entra ID 身份验证。

备选提供方：MiniMax（兼容 OpenAI）

MiniMax 通过兼容 OpenAI 的 API 提供长上下文模型（最多 204K token）。由于 Microsoft Agent Framework 的 OpenAIChatClient 可以对接任意兼容 OpenAI 的终结点，在使用 OpenAIChatClient 的课程里，你可以把 MiniMax 作为直接替换的备选方案。

请把这些变量添加进你的 .env 文件：

示例模型：MiniMax-M3（推荐）、MiniMax-M2.7、MiniMax-M2.7-highspeed（响应更快）。模型名称和可用性会随时间变化，能否访问某个模型也取决于你的账号。

使用 OpenAIChatClient 的代码示例（例如第 14 课的酒店预订工作流）会在 MINIMAX_API_KEY 已设置时，自动检测并使用你的 MiniMax 配置。

备选提供方：Novita AI（兼容 OpenAI）

Novita AI 为开源与前沿大模型（DeepSeek、Llama、Qwen 等）提供兼容 OpenAI 的 API。由于 Microsoft Agent Framework 的 OpenAIChatClient 可以对接任意兼容 OpenAI 的终结点，你可以把 Novita AI 作为 Azure OpenAI 或 OpenAI 的直接替换方案。

请把这些变量添加进你的 .env 文件：

示例模型：moonshotai/kimi-k3、zai-org/glm-5.2、deepseek/deepseek-v4-flash-0731。Novita AI 还托管许多其他开源模型系列（Llama、Qwen、GLM 等）—— 当前可用模型及其模型 ID 请查看 Novita AI 模型库。

目前的示例不会自动读取 NOVITA_* 变量。要使用 Novita AI，请在你运行的示例中构造 OpenAIChatClient 时显式传入这些值。

备选提供方：Foundry Local（在设备本地运行模型）

Foundry Local 是一个轻量运行时，通过兼容 OpenAI 的 API 完全在你自己的机器上下载、管理和提供语言模型服务 —— 不需要云端。

由于 Microsoft Agent Framework 的 OpenAIChatClient 可以对接任意兼容 OpenAI 的终结点，Foundry Local 是 Azure OpenAI 的本地直接替换方案。

1. 安装 Foundry Local

```bash

Windows

winget install Microsoft.FoundryLocal

macOS

brew install foundrylocal ```

2. 下载并运行一个模型（这同时会启动本地服务）：

bash foundry model list # 查看可用模型 foundry model run phi-4-mini

3. 安装用于发现本地终结点的 Python SDK：

bash pip install foundry-local-sdk

4. 让 Microsoft Agent Framework 指向你的本地模型：

```python from foundry_local import FoundryLocalManager from agent_framework.openai import OpenAIChatClient

需要时先下载模型并在本地提供服务，然后发现终结点/端口。

manager = FoundryLocalManager("phi-4-mini")

chat_client = OpenAIChatClient( base_url=manager.endpoint, # 例如 http://localhost:/v1 api_key=manager.api_key, # Foundry Local 始终为 "not-required" 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.", ) ```

注意： Foundry Local 暴露的是兼容 OpenAI 的 Chat Completions 终结点。请把它用于本地开发和离线场景。要使用完整的 Responses API 功能（有状态对话等），请用 Azure OpenAI 或 Microsoft Foundry 项目。

第 8 课的额外配置（Bing Grounding 工作流）

第 8 课的条件工作流 notebook 通过 Microsoft Foundry 使用 Bing grounding（必应搜索接地）。如果你打算运行这个示例，请把下面这个变量添加进 .env 文件：

故障排查

macOS 上的 SSL 证书验证错误

如果你在 macOS 上遇到类似下面的错误：

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

这是 macOS 上 Python 的一个已知问题：系统 SSL 证书没有被自动信任。请按顺序尝试以下方案：

方案 1：运行 Python 自带的 Install Certificates 脚本（推荐）

```bash

把 3.XX 换成你安装的 Python 版本（例如 3.12 或 3.13）：

/Applications/Python\ 3.XX/Install\ Certificates.command ```

方案 2：在 notebook 中使用 connection_verify=False（仅限 GitHub Models 的 notebook）

第 6 课的 notebook（06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb）里已经准备了一段被注释掉的变通代码。遇到证书错误时，取消 connection_verify=False 的注释即可：

python client = ChatCompletionsClient( endpoint=endpoint, credential=AzureKeyCredential(token), connection_verify=False, # 遇到证书错误时关闭 SSL 验证 )

⚠️ 警告： 关闭 SSL 验证（connection_verify=False）会跳过证书校验，降低安全性。只在开发环境里把它作为临时变通方案使用。生产环境绝不要这样用。

方案 3：安装并使用 truststore

bash pip install truststore

然后在 notebook 或脚本开头、发起任何网络调用之前，加入以下内容：

python import truststore truststore.inject_into_ssl()

卡住了？

如果你在按本文配置时遇到任何问题，欢迎来我们的 Azure AI 社区 Discord 聊聊，或者提交一个 issue。

下一课

现在你已经准备好运行本课程的代码了。祝你在学习 AI 智能体的道路上收获满满！

AI 智能体入门与智能体使用场景