月明的文档中心 分享AI实践与思考
入门
上手
教程
基础
概念解释
Microsoft Foundry
开发工具
操作指南
参考
治理与网络
工具与知识
概念解释
操作指南
Agent Service
总览
概念解释
Azure OpenAI
API 与开发
总览
Azure AI Search
权限与安全
参考
检索概念
概念解释
快速上手
教程
Foundry Tools
其他与已退役
总览
概念解释
RAG 与知识工程
智能体与工具
MCP 与 Skills
操作指南
基础
评测、观测与安全
安全
评测
概念解释
参考
企业架构与成本
解决方案场景
样例与学习资源
附录
部署 hosted agent（azd）
本教程用 Azure Developer CLI（azd）初始化一个基础的托管智能体（hosted agent），完成本地运行、远程部署与调用，主线为“初始化、预配、本地测试、部署、调用”。
前置条件
- 有效的 Azure 订阅。
- 已有 Foundry 项目：需要项目范围的 Foundry Project Manager 角色；若需新建项目：需要资源组范围的 Owner 角色。
- 已安装 Foundry Dev Pack（包含 azd 与 Foundry 扩展）；官方要求 azd 1.27.1 或更高版本。
- 已用
azd auth login登录。
- 已把 Application Insights 连接到项目，并有权限读取云端追踪。
步骤
- 初始化示例：在空目录中运行
azd ai agent init，指定 Agent Framework 基础示例的azure.yaml模板，并使用--deploy-mode code --src .。选择“新建 Foundry 项目”或“使用已有项目”。
- 检查配置：确认
azure.yaml中的智能体名称与模型部署。Python 项目需要在服务的env中加入PYTHONNOUSERSITE: "1"。
- 预配资源：运行
azd provision，按azure.yaml创建缺失的资源（例如模型部署）。
- 本地测试：运行
azd ai agent run，它会创建虚拟环境、安装依赖并打开 Agent Inspector，可在浏览器中对话。
- 部署：运行
azd deploy，azd 把源码打包上传，由 Foundry 远端构建并部署。
- 远程调用：运行
azd ai agent invoke "Write a haiku about deploying cloud applications."，可选运行azd ai agent monitor --follow查看容器日志。
参数
参数或文件 | 作用 |
--deploy-mode code | 以源码方式部署（由 Foundry 构建镜像） |
--src . | 在当前目录初始化，后续命令都应在该目录执行 |
--model-deployment <名称> | 复用项目中已有的模型部署 |
--agent-name <名称> | 指定智能体名称 |
azure.yaml | 定义服务、启动命令、环境变量与资源 |
预期结果
步骤 | 检查点 |
初始化 | 当前目录出现 azure.yaml 与示例源码 |
预配 | 资源创建成功，无报错 |
本地运行 | Agent Inspector 打开，本地对话有回复 |
部署 | 输出中有 Agent playground 链接与 Agent endpoint |
远程调用 | 返回一段俳句类回复 |
常见问题
现象 | 可能原因 | 处理 |
azd ai agent init 失败 | azd 版本过低或扩展未更新 | 运行 azd version 检查版本并升级 |
认证失败 | 凭据过期 | 运行 azd auth logout 后重新 azd auth login |
远端构建失败 | main.py 或 requirements.txt 不在上传的 zip 根目录，或模型部署名不存在 | 检查源码结构与模型部署名 |
本地端口冲突 | 8088 端口被占用 | 关闭占用进程 |
Windows ARM64 本地构建失败 | 部分依赖缺少预编译 wheel | 跳过本地运行，直接 azd deploy 后远程调用 |
清理资源
- 若环境是为本教程新建的项目，
azd down会删除项目资源组及其全部资源，并需要确认。
- 若选择的是已有项目，
azd down不会删除该项目，需手动删除本次创建的资源。
限制与待核实
- 官方页面的更新日期为 2026-10-26。页面前置条件写 azd 1.27.1 或更高，排错表又写 1.36.0 或更高，两处不一致，以实际安装时的官方说明为准，待核实（2026-11-05 获取）。
- 本页只覆盖 azd 路径；Python SDK、C#、VS Code 与编码助手路径未展开。
- 托管智能体的区域、配额与计费：待核实（2026-11-05 获取）。
来源与核对
- 来源：Quickstart: Deploy your first hosted agent（https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent）
- 来源：What is Microsoft Foundry Agent Service?（https://learn.microsoft.com/en-us/azure/foundry/agents/overview）
- 核对范围：正文已读（快速入门的 azd 路径与排错表已读；其他路径未展开）。
上一篇
语音 agent
下一篇
创建 prompt agent
Loading...