你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
本文介绍如何从 Python 或 .NET 源代码在 Foundry 代理服务中部署 Hosted agent,而无需生成或推送容器映像。 你上传代码的 .zip(也可以选择上传依赖项),代理服务会直接按原样运行它,或者在云端为你构建依赖项。
Tip
对于大多数方案,请使用 Azure Developer CLI (azd) 或用于 VS Code 的 Foundry Toolkit 进行部署。 这些工具会替你处理繁重工作:它们会打包你的源代码、将其上传、轮询 active,并自动配置基于角色的访问控制。 要开始使用,请按照 快速入门:部署第一个托管代理 操作,并在系统提示选择部署方法时选择 代码(或 源代码(ZIP 上传))。
如果需要以编程方式部署源代码代理(从自己的应用程序中Python SDK 或.NET SDK,或者直接通过 REST API 进行自定义工具、与语言无关的自动化或与现有持续交付系统的集成),请使用本文中的 SDK 和 REST 过程。 在本文中,你将完成以下任务:
- 选择 依赖项解析模式 并打包源。
- 创建代理,等待它到达
active并调用它。 - 更新、查看版本、下载和流式传输已部署代理的日志。
如果需要完全控制运行时映像或已有一个正常工作的 Dockerfile,请使用基于容器的路径: 部署托管代理。
如果使用编码代理(如GitHub Copilot)打包和部署源代码,Microsoft Foundry 技能可帮助准备项目并遵循所需的 azdSDK 或 REST 步骤。
先决条件
- 支持区域中的 Microsoft Foundry 项目。
- Azure CLI 2.80 或更高版本,并登录到拥有该项目的租户。
pip使用 Python 3.13 或更高版本在本地打包源代码。版本 2.2.0 或更高版本的
azure-ai-projects和azure-identity包。pip install "azure-ai-projects>=2.2.0"
支持的运行时
code_configuration.runtime代理定义中的字段接受以下值。 选择与你的 zip 包中二进制文件匹配的运行时 — 对于 Python,选择 Linux x86_64 wheel;对于 .NET,选择 TargetFramework 输出中的 dotnet publish。
| 语言 | 运行时值 |
|---|---|
| Python |
python_3_13、python_3_14 |
| .NET | dotnet_10 |
语言版本支持策略
代理服务运行时会为每个 code_configuration.runtime 的值包含平台构建的容器映像。 为使部署的代理完全受支持,Foundry 将托管代理语言支持与每种语言的生命周期终止支持保持一致。 该语言版本的支持将于社区停止支持之日终止。 当平台约束(例如底层基础映像)要求时,Microsoft 可能会提前停用某个 code_configuration.runtime 值。
有关上游支持终止计划,请参阅:
- Python:Python版本的Status(python.org)。
- .NET:.NET和.NET核心支持策略。
退役阶段
语言生命周期结束日期后,仍可以创建、更新和运行使用已停用运行时值的托管代理。 但是,在通过设置当前的 code_configuration.runtime 值并重新部署将这些代理升级到受支持的运行时之前,它们将无法获得支持、新功能或安全补丁。
所需的权限
你需要在项目范围拥有 Foundry 项目经理角色才能部署托管智能体。 此角色授予创建和更新代理所需的数据平面权限,并在需要时具备为平台创建的代理标识创建角色分配的能力。 有关涉及权限的详细细分,请参阅 托管代理权限参考。
Important
Foundry RBAC 角色最近已更名。 Foundry 用户、Foundry 所有者、Foundry 帐户所有者和 Foundry 项目经理之前的名称分别为“Azure AI 用户”、“Azure AI 所有者”、“Azure AI 帐户所有者”和“Azure AI 项目经理”。 在重命名推出时,你仍可能会在某些位置看到以前的名称。重命名后,角色 ID 和核心权限保持不变。
你的代理以平台分配的托管标识运行,独立于你的用户身份。 默认情况下,此标识可以通过项目终结点和会话存储访问模型推理。 对于外部资源(例如,你自己的Azure 存储),请手动将 RBAC 角色分配给代理的Microsoft Entra ID。 有关详细信息,请参阅 代理访问超出默认值。
部署生命周期
每个源代码部署都遵循相同的顺序: 包 -> 创建或更新 -> 轮询,直到 active -> 调用。 源代码路径在代理定义中使用 code_configuration 表示。 基于映像的路径改用 container_configuration 。 在同一版本中,这两个选项互斥。
选择适合工作流的路径。 如果不确定,请从Azure开发人员 CLI 或 VS Code 开始,这是大多数客户的建议路径。
| 路径 | 最适用于 | 包装 |
|---|---|---|
| Azure 开发人员 CLI 或 VS Code | 大多数部署,包括首次部署和最快的内部迭代循环。 | 构建工具会为您构建并上传 ZIP 文件。 |
| Python SDK | 通过 Python 应用或自动化流程以编程方式进行部署。 | 生成 zip;SDK 上传它。 |
| .NET SDK | 通过 .NET 应用或自动化进行编程式部署。 | SDK 会为你压缩文件夹。 |
| JavaScript/TypeScript SDK | 通过 Node.js 应用或自动化脚本以编程方式进行部署。 部署 Python 或 .NET 源代码;没有 Node.js 托管运行时环境。 | 生成 zip;SDK 上传它。 |
| REST API | 自定义工具、与语言无关的自动化和 CD 系统。 | 构建 ZIP 文件并发送 multipart 请求。 |
选择如何解析依赖项
在开始之前,请为 code_configuration.dependency_resolution 选择一个值。 此选项会影响你在 zip 中放置的内容。
| 价值 | Behavior | 何时使用 |
|---|---|---|
remote_build |
代理服务从 requirements.txt (Python) 安装依赖项,或在预配期间还原项目文件(.NET)。 |
你想要较小的上传量和最简单的内循环。 建议首次用户使用。 |
bundled |
ZIP 文件按原样运行。 在 packages/ (Python) 或 dotnet publish 输出(.NET)中交付预生成的 Linux 依赖项。 |
你需要可重现的构建、你的依赖是私有的或仅限 wheel,或者你的项目无法在服务端干净地还原。 |
对于打包模式,请参阅 手动打包 ZIP 文件 以了解本地构建命令。
专用虚拟网络的防火墙要求
如果使用专用虚拟网络保护项目,请在部署之前更新网络策略以允许出站连接到以下终结点。
所有源代码部署都需要对以下目标具有出站访问权限:
mcr.microsoft.com*.login.microsoft.com
使用 Foundry 托管库(如 azure-ai-agentserver-core 或 agent-framework-foundry-hosting)的代理代码还会从代理发送遥测数据。 允许这些端点,以免追踪数据被丢弃:
-
agent365.svc.cloud.microsoft(TCP 443):当为您的 Foundry 资源启用 Agent 365 数据收集时,用于 Agent 365 可观测性数据导出。 如果阻止该代理,代理会继续运行,但其跟踪不会导出到 Agent 365。 若要停止此流量,请禁用代理 365 数据收集。 有关更多信息,请参阅为 Microsoft Foundry 配置 Agent 365 数据收集。 - 当你的项目具有 Application Insights 连接时,防火墙允许列表 中列出的 Application Insights 端点。
有关网络配置,请参阅 在虚拟网络中部署托管代理。
使用 Azure 开发人员 CLI 或 VS Code 进行部署
Azure开发人员 CLI(azd)和 Foundry Toolkit for VS Code 自动执行完整的源代码部署生命周期-它们将源打包到 zip 中,计算 SHA-256,上传它,轮询 active,并为你配置基于角色的访问控制。 这些工具是大多数客户的建议路径,也是最快的内部循环。
有关分步演练,请参阅 快速入门:部署第一个托管代理。 当快速入门要求选择部署方法时,请选择“代码”(或“源代码(ZIP 上传)”)。
选择源代码部署
以交互方式运行时 azd ai agent init ,该工具会提示你选择部署模式。 选择从源代码部署代码作为 ZIP 上传,而不是构建容器映像。 代码部署是Python和.NET托管代理的默认模式。 Foundry Toolkit for VS Code 以相同的方式提示你输入部署方法。
若要以非交互方式选择源代码部署,例如,在 CI/CD 管道中传递 --deploy-mode code。 此模式需要 --runtime 和 --entry-point,并接受可选的 --dep-resolution 值:remote_build(默认)或 bundled:
azd ai agent init --no-prompt --project-id "<project-resource-id>" \
--deploy-mode code --runtime python_3_13 --entry-point main.py
初始化后,azd将源代码部署设置写入codeConfiguration中azure.ai.agent服务的azure.yaml字段:
services:
my-agent:
host: azure.ai.agent
project: src/my-agent
kind: hosted
codeConfiguration:
runtime: python_3_13
entryPoint:
- python
- main.py
dependencyResolution: remote_build
env:
PYTHONNOUSERSITE: "1"
对于Python运行时,请在解释器启动前在部署的环境中设置PYTHONNOUSERSITE,如以下部分中的 Python 运行时示例所示。 将依赖项安装在运行时环境中,或将它们与代码捆绑在一起,而不是与 pip install --user 一起。 请参阅“配置Python启动”。
运行 azd up 以预配和部署。 仅在需要构建或引用容器映像时,才使用 --deploy-mode container。
如果需要从自己的应用程序以编程方式部署或与现有工具集成,请使用以下部分中的 SDK 或 REST 路径。
使用 CLI 下载已部署的源
要检查或恢复代码部署的智能体的源,请下载并提取它:
azd ai agent code download my-agent --dest ./downloaded-source
位置值是 azd 服务名称。 项目有一个代理服务时省略它。 使用 --version 下载特定版本,或使用 --zip 保存原始存档,而不是提取它:
azd ai agent code download my-agent \
--version 2 --zip --dest ./my-agent-v2.zip
此命令适用于基于代码的托管代理,不适用于基于映像的代理。
从源代码进行部署
选择语言或界面。 每个选项卡都经历相同的生命周期:创建代理,轮询直到其达到 active,调用它,并下载已部署的代码。
使用 Python SDK 通过您自己的应用程序或自动化流程部署源代码代理。 你自行生成 zip 并将其字节和 SHA-256 传递给 SDK,该 SDK 上传它并公开与 REST API 相同的创建、轮询、调用和下载操作。 代码部署需要 azure-ai-projects 版本 2.2.0 或更高版本。
构建 ZIP 文件
Python SDK 会上传你构建的 zip。 使用 手动打包 zip 中所述的相同布局和依赖项解析规则。 最小的 remote_build 负载是一个扁平的 ZIP 压缩包,main.py 和 requirements.txt 位于其根目录下。
创建代理
import hashlib
from pathlib import Path
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
CodeConfiguration,
HostedAgentDefinition,
ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential
# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")
code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()
credential = DefaultAzureCredential()
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=credential,
)
created = project.agents.create_version_from_code(
agent_name=AGENT_NAME,
definition=HostedAgentDefinition(
cpu="1",
memory="2Gi",
code_configuration=CodeConfiguration(
runtime="python_3_13",
entry_point=["python", "main.py"],
dependency_resolution="remote_build",
),
protocol_versions=[
ProtocolVersionRecord(protocol="responses", version="2.0.0")
],
environment_variables={
"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini",
"PYTHONNOUSERSITE": "1",
},
),
code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
code_zip_sha256=code_zip_sha256,
description="Hello-world code agent",
)
print(f"Created version: {created.version}")
对于调用协议,请将 protocol_versions 条目设置为 ProtocolVersionRecord(protocol="invocations", version="2.0.0"). 对于调用 (WebSocket) 协议,请使用 ProtocolVersionRecord(protocol="invocations_ws", version="2.0.0")。 对于 bundled 模式,请在 zip 中设置 dependency_resolution="bundled" 并包括预生成依赖项。 有关详细信息,请参阅 在本地生成 Linux 依赖项。
轮询活动状态
import time
while True:
version = project.agents.get_version(
agent_name=AGENT_NAME, agent_version=created.version
)
status = version["status"]
print(f"Status: {status}")
if status == "active":
break
if status == "failed":
raise RuntimeError(f"Provisioning failed: {version.get('error')}")
time.sleep(5)
请参阅Poll for active,了解状态值的完整列表以及在失败时如何读取error对象。
调用代理
版本到达 active后,将 OpenAI 客户端绑定到代理终结点并调用它。 此示例使用响应协议:
openai_client = project.get_openai_client(agent_name=AGENT_NAME)
response = openai_client.responses.create(input="Hello! What can you do?")
print(response.output_text)
对于调用协议,直接使用持有者令牌调用调用终结点,如调用智能体中所示。
下载已部署的 ZIP 文件
通过下载 ZIP 文件并将其 SHA-256 与你上传的值进行比较,准确验证实际部署的内容:
import hashlib
from pathlib import Path
out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
for chunk in project.agents.download_code(
agent_name=AGENT_NAME, agent_version=created.version
):
f.write(chunk)
sha.update(chunk)
print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")
有关完整的可运行示例,请参阅 Python 托管代理示例。
手动打包 zip
如果使用 azd,请跳过本部分,azd 为你生成 zip。 如果使用 REST API、切换到 捆绑 依赖项解析,或者需要完全控制上传内容,请阅读它。
ZIP 压缩包必须在根目录平铺——不能有顶层外层文件夹。
选择与您的代理所用语言对应的选项卡。
Python布局(远程生成模式)
该服务从 requirements.txt中安装云中的依赖项。
agent-code.zip
+-- main.py
+-- requirements.txt
Python布局(捆绑模式)
您在 packages/ 中提供预构建的 Linux 依赖项。
agent-code.zip
+-- main.py # entry point
+-- requirements.txt
+-- packages/ # extracted modules (not raw .whl files)
+-- azure/identity/__init__.py
+-- requests/__init__.py
在本地生成 Linux 依赖项(捆绑的、Python)
使用 manylinux2014_x86_64 平台标签,以便 pip 即使在 Windows 或 macOS 上也能下载 Linux wheel 包。
Bash
pip install -r requirements.txt \
--target packages/ \
--platform manylinux2014_x86_64 \
--python-version 3.13 \
--implementation cp \
--only-binary=:all:
zip -r agent-code.zip main.py requirements.txt packages/
PowerShell/Windows cmd
pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:
tar -a -c -f agent-code.zip main.py requirements.txt packages
--only-binary=:all: 强制使用 wheel 包(禁用源码构建)。
--python-version 必须与代理定义中的 runtime 值匹配。
Warning
导致 session_creation_failed 或 ModuleNotFoundError 的常见包装错误:
- 将源文件封装在文件夹中(使用
my-agent/main.py,而不是位于根目录的main.py)。 - 在
.whl中包含原始packages/文件,而不是提取出的模块。 - 为 Linux 运行时捆绑 Windows 二进制文件(
.pyd、.dll)。
限制
| 限制 | 价值 |
|---|---|
| 最大 zip 大小(多部分上传) | 250 MB |
有关支持的 cpu 和 memory 组合,请参阅 沙盒大小。
故障排除
| 症状 | 可能的原因 | 修复 |
|---|---|---|
401 Unauthorized |
令牌缺失或作用域错误。 | 使用 --resource https://ai.azure.com 获取令牌。 |
403 Forbidden |
调用方不具备该项目的基于角色的访问控制权限 | 在项目范围授予 Foundry 智能体使用者(仅调用)或 Foundry 用户(也可开发)。 |
创建时提示 409 conflict (Agent '<name>' already exists) |
代理名称已存在 | 使用 Update (POST /agents/{name}),或选取新名称。 |
400 bad_request (CPU and Memory must be specified as a valid resource tier) 在创建或更新时 |
cpu
/
memory 不是受支持的层级之一 |
将 cpu 和 memory 设置为来自 Sandbox sizes 的一组有效组合。 |
调用时提示 400 bad_request (Agent version is still being provisioned) |
新版本正在部署中,活跃版本正在被调换。 | 轮询版本 status,直到 active,然后重试。 |
调用时提示 424 session_not_ready |
容器已启动,但 /readiness 未在超时时间内返回 HTTP 200 |
使用 :logstream 流式查看日志,修复就绪探针或启动错误,然后重新部署。 |
删除代理时提示 409 conflict (Agent has active sessions) |
打开的会话会阻止删除。 | 等待会话变为空闲状态,或追加 &force=true 以级联删除会话。 |
版本停滞在 creating(>10 分钟,,远程构建) |
服务器构建失败或无法解析 requirements.txt |
切换到 dependency_resolution: bundled 并在本地进行预构建。 |
| 专用虚拟网络中的部署失败 | 所需的出站终结点被防火墙阻止 | 允许防火墙要求中针对专用虚拟网络的终结点,然后重新部署。 |
版本过渡到 failed |
错误的 zip 布局、语法错误或 (remote_build) 还原/编译失败 |
首先读取该版本的 error 对象——error.code 对失败进行分类,error.message 包含底层的包还原或编译错误行(Python 的 pip、.NET 的 NuGet)以及故障排除链接。 验证 文件夹结构。 仅在容器启动后使用 :logstream 。 |
ModuleNotFoundError 在运行时 |
缺少 packages/,包含原始.whl 文件,或包含Windows二进制文件 |
使用 pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all: 重新构建。 |
下载时提示 409 AgentNotCodeBased |
代理基于镜像 | 使用 基于容器的部署文档。 |
清理资源
如果从快速入门azd中搭建了项目基架,请从项目根目录运行azd down以删除整个预配的环境。
若要删除使用 SDK 或 REST API 部署的代理,请使用下面的匹配路径。
# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)
# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)
Warning
删除代理会删除其所有版本并终止活动会话。 无法撤消此操作。