在 Azure AI Foundry 里建 Agent：微软 AI Agent 入门课给的完整步骤

2026-08-18

很多人翻 ai-agents-for-beginners 是奔着 notebook 去的，结果卡在第一步：FoundryChatClient 一实例化就报环境变量缺失，而缺的那两个值到底从门户哪个页面抄，课程正文并没有和 notebook 放在一起。这个仓库其实把门户操作单独拆成了一份练习文档，路径是 02-explore-agentic-frameworks/azure-ai-foundry-agent-creation.md。注意文件名还叫 azure-ai-foundry-，但正文标题已经改成了 Microsoft Foundry Agent Service Development，并在开头补了一句注记：Microsoft Foundry 的旧名是 Azure AI Studio。按文件名搜和按正文词搜会搜到不一样的结果，这一点先记住。

这篇文章讲的是这份练习文档写明的流程，以及它和 00-course-setup/README.md 里那套环境配置怎么衔接。

一、前置条件：文档明确要求的资源与权限

练习文档的 Prerequisites 只列了两条，但两条都卡人。

第一条是一个有活跃订阅的 Azure 账号。第二条是权限：你需要有创建 Microsoft Foundry hub 的权限，或者由别人替你创建好；文档补了一句判断口径——如果你的角色是 Contributor 或 Owner，就可以按这份教程往下走。换句话说，公司订阅里只给了你 Reader 的话，这份练习你自己是走不完的，得先找管理员建 hub。

代码侧的前置条件不在这份练习文档里，在 00-course-setup/README.md。那边写明需要 Python 3.12+，用 .NET 示例的话需要 .NET 10 SDK 或更高，另外要装 Azure CLI 用于认证。Windows 上建虚拟环境后的激活方式文档给的是：

venv\Scripts\activate

zsh/bash 那侧是 source venv/bin/activate，两条别抄串了。

依赖装在 requirements.txt 里。这个文件有个细节值得留意：它把 agent-framework-core 直接钉在 1.10.0，注释说明 1.11.0 引入了课程 notebook 会用到的破坏性变更——移除了 ChatMessage 与 HostedWebSearchTool、改了 Message 的构造方式、并去掉了 Agent.run() 上的 model= 参数；同时注释还说明为什么不走 agent-framework 元包，是为了避免 [all] extras 拉进未钉版本的集成子包造成 pip 冲突。这是仓库当前的钉版，随版本可能变动，但它提醒你一件事：装依赖时别顺手 -U 升级这几个包。

二、门户里的四步，每步在改什么

第一步，建 hub 和 project。 练习文档没有把门户点击路径全写出来，而是让你按 Microsoft Foundry 的官方指引建 hub，建完 project 后关掉提示、看一眼项目页。这一步产出的是后面所有东西的容器：模型部署和 agent 都挂在 project 下面。

第二步，部署模型。 路径写得很具体：左侧 My assets 里选 Models + endpoints 页面，在 Model deployments 标签页的 + Deploy model 菜单里选 Deploy base model，然后搜 gpt-5-mini 选中确认。gpt-5-mini 是仓库里给出的示例模型名，不是唯一选项。文档在这一步只加了一句注记：调低 TPM 有助于避免过度占用订阅里的可用配额——它没给具体数值，你也不必去猜。

这一步真正产出的东西是部署名，不是模型名。后面 notebook 要的是部署名，两者可以不同，这是新手最容易记混的地方。

第三步，建 agent。 左侧 Build & Customize 里选 Agents 页面，点 + Create agent，在 Agent Setup 对话框里做三件事：给 agent 起名（文档的示例名是 FlightAgent）、确认选中的是刚才部署好的那个模型、填 Instructions。文档给了一段完整的 Instructions 示例，结构是三段式：先做意图识别（列出搜航班、按 flight ID 查详情、查座位余量、按航班号查实时状态这几类），再按意图处理请求并对日期、航班号、ID 这类输入做格式校验，最后规定回复语气与出错时的兜底说法。这段示例值得读的不是它的措辞，而是它把「校验不通过怎么办」「查不到数据怎么办」都写进了 Instructions，而不是留给模型自由发挥。

同一屏上还有 Knowledge Base 和 Actions 两块，文档明说这次练习跳过它们。

第四步，试跑。 在 agent 的 Setup 面板顶部点 Try in playground，在聊天窗里提问。文档在这里放了一句很关键的注记：这个练习里没有接任何实时数据，所以 agent 的回答可能并不准确，这一步测的是它能不能按 Instructions 理解并回应，不是测答案对不对。

练习结束后文档要求清理：去 Azure 门户找到部署 hub 资源的那个资源组，工具栏上选 Delete resource group，输入资源组名确认删除。这一步别跳，门户里建出来的东西是持续计费的资源。

三、和代码侧的衔接：只有两个变量

门户走完之后，notebook 认的其实只有两个环境变量。00-course-setup/README.md 里给出的 .env 示例就是这两行（.env.example 里同名的两项在，只是值写成了占位符）：

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

00-course-setup/README.md 给了取值位置的对照表：AZURE_AI_PROJECT_ENDPOINT 在 Foundry 门户的项目 Overview 页面，AZURE_AI_MODEL_DEPLOYMENT_NAME 在 Models + Endpoints 里选中你部署的模型后看它的 Deployment name。

复制 .env 的命令两个平台不一样，Windows 侧是：

Copy-Item .env.example .env

zsh/bash 侧是 cp .env.example .env。

认证不走 key。00-course-setup/README.md 写明大部分 notebook 通过 azure-identity 里的 AzureCliCredential 或 DefaultAzureCredential 复用你的 Azure CLI 登录态，所以要先：

az login

在没有浏览器的远程环境或 Codespace 里用 az login --use-device-code。

拿到这两个变量之后，02-explore-agentic-frameworks/code_samples/02-python-agent-framework.ipynb 里的客户端就是这样建的：

provider = FoundryChatClient(
    project_endpoint=endpoint,
    model=model,
    credential=AzureCliCredential()
)

这里 endpoint 和 model 分别读的就是上面那两个变量，notebook 在建客户端之前先做了一次判空，两个有任一缺失就直接 raise ValueError。再往下，工具用 @tool(approval_mode="never_require") 装饰普通 Python 函数，agent 由 provider.as_agent(name=..., instructions=..., tools=[...]) 建出来，多轮对话靠 agent.create_session() 返回的 session 传给 agent.run()。

以上为按仓库代码中的接口语义组合的示例，未经实测，以仓库最新代码为准。

四、边界：几处必须知道的落差

Foundry Agent Service 处于 Public Preview。 02-explore-agentic-frameworks/README.md 写明它当前是 Public Preview，支持用 Python 和 C# 构建 agent。预览状态的服务，接口和门户位置都可能变。

门户里建的 agent，练习文档没给「在代码里取回来」的步骤。 这份练习从建 agent 一路走到 playground 就结束了，怎么按 agent 的 id 在 notebook 里连上门户里那个 FlightAgent，仓库里我们没有找到对应说明。02 课的 Python notebook 走的是另一条路：在代码里用 provider.as_agent() 现场建 agent，和门户里那个不是同一个对象。别以为门户建完 notebook 就能直接用。

README 里的 SDK 示例和当前的环境变量不是一套。 02-explore-agentic-frameworks/README.md 里那段 Foundry Agent Service 的 Python 示例用的是 AIProjectClient.from_connection_string(conn_str=...)，走的是连接字符串；而 .env.example 和课程配置那一课给的是 project endpoint。两处并存，照哪段抄要看清楚。同一课里还有一处小落差：notebook 的说明文字和小结表格里写的是 provider.create_agent()，代码单元格里实际调用的是 provider.as_agent()——以能跑的代码单元格为准。

GitHub Models 这条老路线已经标为 deprecated。 .env.example 的注释写明它已弃用、且不支持 Responses API，所有示例改走 Azure OpenAI；02 课的 Azure OpenAI 版 notebook 开头的迁移注记也写明这份示例原先用的是 Semantic Kernel 加 GitHub Models，现已换成 Microsoft Agent Framework 加 Azure OpenAI。翻到旧教程时别再照抄。

Python 有两个 02 版本，别混。 02-python-agent-framework.ipynb 走 Foundry project（FoundryChatClient），02-python-agent-framework-azure-openai.ipynb 走 Azure OpenAI 的 Responses API（OpenAIChatClient，读的是 AZURE_OPENAI_ENDPOINT 和 AZURE_OPENAI_DEPLOYMENT）。.NET 示例在同目录的 02-dotnet-agent-framework.cs。

五、怎么验证真的配对了

第一层，验登录态。00-course-setup/README.md 给的是：

az account show

第二层，验模型部署确实存在。.agents/skills/testing-course-samples/SKILL.md 的前置检查里给了这条：

az cognitiveservices account deployment list -g <rg> -n <account> -o table

输出里那个 name 才是应该填进 AZURE_AI_MODEL_DEPLOYMENT_NAME 的值。

第三层，跑 notebook。仓库带了一个批量执行器 scripts/validate-notebooks.ps1，同一份 skill 文档里给的单课用法是：

pwsh scripts/validate-notebooks.ps1 -Filter '08-*' -Timeout 600

把课号换成你要跑的那一课即可；-Timeout 是每个单元格的超时，上面那个值只是文档示例里给的写法，不是什么推荐配置。skill 文档还写明该脚本会把执行副本、逐 notebook 日志和 results.json 写到临时目录，并以失败数作为退出码；-List 只列出会跑哪些而不执行；如果 python 不在 PATH（Windows 上常见于应用商店别名），用 -Python 显式指定解释器路径。另外它说明了 .NET notebook 默认被排除，要跑得加 -IncludeDotnet。

如果只想确认 02 这一课通没通，最省事的其实是直接在 notebook 里跑那个判空单元格：不报 ValueError 就说明两个变量都读到了，接下来若还失败，问题多半在权限或部署名，而不在 .env。

本文依据 github.com/microsoft/ai-agents-for-beginners 仓库于 2026-08-18 的公开内容整理，事实来自仓库内的课程正文与代码示例。我们没有跑过文中涉及的代码，因此不涉及运行结果、耗时与 Agent 实际表现的任何描述。该课程持续更新，文中涉及的文件路径、依赖与接口写法随版本变动，请以仓库最新内容为准。文中涉及的云端服务调用会产生费用并可能上传数据，请自行评估密钥与数据边界。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。