你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速启动：部署第一个托管代理

先决条件

在开始之前，需要：

Azure subscription--免费创建一个订阅。
如果您有现有 Foundry 项目，您在项目范围需要 Foundry Project Manager。如果要创建新的 Foundry 项目，则需要在资源组范围内拥有 Owner 角色。有关完整角色矩阵，请参阅托管代理权限参考。
Python 3.13 或更高版本。

Azure Developer CLI （AZD） 1.25.3 或更高版本。
扩展名 azd microsoft.foundry 。安装并验证安装 AZD 后的扩展：
```
azd ext install microsoft.foundry
```

Azure CLI安装和身份验证：
```
az login
```

本快速入门中使用的Python SDK 包：

pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

包含已部署模型的现有 Foundry 项目。本快速入门中的Python SDK 路径将创建和路由托管代理版本，但它不会为新的 Foundry 项目搭建基架或为你创建模型部署。如果需要完整的预配工作流，请使用本文中的Azure开发人员 CLI 选项卡。

安装了 Microsoft Foundry Skill 的编码代理主机。
已安装并经过身份验证的Azure CLI和Azure开发人员 CLI（AZD）：
```
az login
azd auth login
```

步骤 1：初始化示例代理

使用空目录中的基本 Agent Framework 示例初始化新的托管代理：

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml" --deploy-mode code

交互式流会提示输入以下内容：

智能体名称：自定义名称或接受默认名称 - agent-framework-agent-basic-responses
Foundry 项目：选择 创建新的 Foundry 项目 或 使用现有的 Foundry 项目
Tenant：选择Azure租户
Subscription：选择Azure订阅
Location：选择Azure区域
模型：选择默认的 gpt-5.4-mini 或可以访问的其他模型。
模型版本：选择默认选项。
模型 SKU：选择一个有可用配额且不是 Batch 的选项，通常为 Standard 或 GlobalStandard
部署容量：选择 默认值10
部署名称：选择默认gpt-5.4-mini

完成后，你会看到AI 智能体定义已成功添加到你的 azd 项目中！ 将目录更改为新创建的代理文件夹。

cd agent-framework-agent-basic-responses

步骤 2：预配Azure资源

预配 azure.yaml 中定义的资源：

azd provision

步骤 3：在本地测试代理

azd ai agent run

此命令创建虚拟环境、安装依赖项、使用 startupCommand 定义的代理 azure.yaml启动代理，并在浏览器中打开代理检查器，以便可以与代理聊天。

步骤 4：部署到 Foundry 智能体服务

生成并部署代理容器：

azd deploy

命令完成后，输出会显示指向代理操场和代理终结点的链接：

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

步骤 5：调用代理

向部署的代理发送相同的提示：
```
azd ai agent invoke "Write a haiku about deploying cloud applications."
```
你应该会在几秒钟内看到一首俳句响应。
（可选）与代理交互时流式传输容器日志：
```
azd ai agent monitor --follow
```

步骤 1：创建或选择 Foundry 项目

打开 Foundry 门户并创建 Foundry 项目，或选择现有项目。
在项目中，部署支持聊天的模型，例如 gpt-5.4-mini。
从门户复制这些值：
- 从概述中选择项目终结点。
- 部署名称来自生成>部署。

步骤 2：下载基本示例代理代码

克隆 Foundry 示例存储库。

git clone https://github.com/microsoft-foundry/foundry-samples.git

步骤 3：创建Python环境和配置设置

创建虚拟环境并安装本快速入门所需的Python包。

对于 macOS 或 Linux：

python -m venv .venv
source .venv/bin/activate
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

对于 Windows (PowerShell)：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

为部署脚本创建工作文件夹，然后在该文件夹中创建一个 .env 文件：

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=basic-agent
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/01-basic>

步骤 4：使用 Python 部署托管代理

在与 .env 相同的工作文件夹中创建一个名为 deploy_hosted_agent.py 的文件，内容如下：

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  AgentEndpointConfig,
  CodeConfiguration,
  CodeDependencyResolution,
  FixedRatioVersionSelectionRule,
  HostedAgentDefinition,
  ProtocolConfiguration,
  ProtocolVersionRecord,
  ResponsesProtocolConfiguration,
  VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "basic-agent")
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
  zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
  excluded = {".git", ".venv", "__pycache__", ".env", "deploy_hosted_agent.py"}

  with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
    for path in source_dir.rglob("*"):
      if not path.is_file():
        continue
      if any(part in excluded for part in path.parts):
        continue
      zip_file.write(path, path.relative_to(source_dir))

  return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
  for attempt in range(60):
    time.sleep(10)
    details = project_client.agents.get_version(
      agent_name=agent_name,
      agent_version=version,
    )
    status = details["status"]
    print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

    if status == "active":
      return

    if status == "failed":
      raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

  raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
  code_zip_path.open("rb") as code_stream,
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  original_agent_endpoint = None
  created = None

  try:
    created = project_client.agents.create_version_from_code(
      agent_name=agent_name,
      description="Basic hosted agent deployed from local Python source.",
      definition=HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        code_configuration=CodeConfiguration(
          runtime="python_3_14",
          entry_point=["python", "main.py"],
          dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
        ),
        environment_variables={
          "FOUNDRY_PROJECT_ENDPOINT": endpoint,
          "FOUNDRY_MODEL_NAME": model_name,
        },
        protocol_versions=[
          ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
      ),
      code=code_stream,
    )

    print(f"Created hosted agent version {created.version}")

    wait_for_active_version(project_client, created.version)

    original_agent_endpoint = project_client.agents.get(
      agent_name=agent_name
    ).agent_endpoint
    project_client.agents.update_details(
      agent_name=agent_name,
      agent_endpoint=AgentEndpointConfig(
        version_selector=VersionSelector(
          version_selection_rules=[
            FixedRatioVersionSelectionRule(
              agent_version=created.version,
              traffic_percentage=100,
            ),
          ]
        ),
        protocol_configuration=ProtocolConfiguration(
          responses=ResponsesProtocolConfiguration()
        ),
      ),
    )

    print(f"Agent endpoint configured for version {created.version}")

    with project_client.get_openai_client(agent_name=agent_name) as openai_client:
      response = openai_client.responses.create(
        input="Write a haiku about deploying cloud applications.",
      )

    print(f"Agent response: {response.output_text}")
  finally:
    if original_agent_endpoint is not None:
      project_client.agents.update_details(
        agent_name=agent_name,
        agent_endpoint=original_agent_endpoint,
      )
      print("Agent endpoint restored")

    if created is not None:
      project_client.agents.delete_version(
        agent_name=agent_name,
        agent_version=created.version,
        force=True,
      )
      print(f"Deleted hosted agent version {created.version}")

运行脚本：

python deploy_hosted_agent.py

该脚本压缩示例源，将其上传为新的托管代理版本，等待预配完成，暂时将托管代理终结点路由到该版本，调用已部署的代理，然后还原以前的终结点配置并删除临时版本。

步骤 5：调用代理

脚本完成后，使用以下任一方式使用托管代理：

编辑 deploy_hosted_agent.py 并更改 input 传递给 openai_client.responses.create(...)的值，然后再次运行脚本。
如果想要持久性路由版本而不是临时验证部署，请在查看流量路由影响后改编脚本以跳过还原和 delete_version(...) 步骤。

步骤 1：创建 Foundry 项目

打开命令面板（Ctrl+Shift+P），然后选择 Foundry Toolkit： Create Project。
选择Azure订阅。
创建新的资源组或选择现有资源组。
输入 Foundry 项目的名称。

步骤 2：部署模型

打开命令面板并选择 Foundry 工具包：打开模型目录。
搜索 gpt-4.1，然后选择部署。
在模型部署页面上，选择 Deploy to Microsoft Foundry。

步骤 3：创建托管代理项目

打开命令面板并选择 Foundry Toolkit：创建新的托管代理。
选择 Python 作为语言。
对于“框架”，请选择 “代理框架”。
选择 “响应 API ”作为协议类型。
选择 “基本 ”作为示例代码。
选择“下一步”按钮。
选择项目文件的文件夹，并输入代理的名称。
对于“环境设置”，请选择“使用 Microsoft Foundry 设置”。内容会自动填入您在步骤 1 和 2 中创建的项目和模型。
选择“ 创建 ”按钮。

将打开一个新的 VS Code 窗口，并将该项目设为当前活动工作区。

步骤 4：安装依赖项

创建虚拟环境并安装要求。

对于 macOS 或 Linux：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

对于 Windows (PowerShell)：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

步骤 5：在本地测试代理

按 F5 启动启用了调试的本地 HTTP 服务器。 Foundry Toolkit 代理检查器会打开，以便进行交互式测试，你还可以在代码中设置断点。

在不调试的情况下运行服务器：

python main.py

代理侦听 http://localhost:8088/。使用 curl 发送测试提示（或任何 HTTP 客户端）：

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

步骤 6：部署到 Foundry 智能体服务

打开命令面板并选择 Foundry Toolkit：部署托管代理。将打开部署 Web 视图。
对于 部署方法，请选择 “代码”。
选择 “远程 ”作为包模式。
代理名称会自动填充。
选择“下一步”按钮。
“审阅和部署”页会自动填入内容。
选择“ 部署 ”按钮。

部署完成后，代理将显示在 Foundry Toolkit 资源管理器中的 托管代理（预览版） 下。

步骤 7：调用代理

在 Foundry Toolkit 资源管理器中，展开 托管代理（预览版），然后选择你的代理。详细信息页显示 “部署详细信息”下的状态。
选择 “操场 ”选项卡并发送测试提示，例如 Write a haiku about deploying cloud applications.。

如果使用编写的示例脚本，则它已还原终结点配置，并在验证后删除临时托管代理版本。
如果为此快速入门创建了专用资源组，则不再需要项目或模型部署后，可以从 Azure 门户中删除资源组。

警告

删除资源组会永久删除其中的所有内容，包括 Foundry 项目、模型部署、容器注册表、Application Insights 和托管代理。

步骤 1：使用 Foundry 技能打开工作区

在编码代理主机中打开一个空文件夹，例如Visual Studio Code、Copilot CLI 或 Claude Code 中的GitHub Copilot。在要求编码代理创建 Azure 资源之前，请先确认 microsoft-foundry 技能可用。

如果该技能不可用，请参阅在编码代理中使用 Microsoft Foundry 技能。

步骤 2：请求技能创建托管智能体

让你的编码代理使用该技能完成整个托管代理工作流：

Use the Microsoft Foundry Skill hosted-agent quick-start workflow to create my
first hosted agent end to end. Verify my environment first, and stop if I need
to sign in myself. Use Python 3.13, Agent Framework, the Responses API, the
Basic sample, and code deployment. Create a new Foundry project unless I provide
an existing project. Use the model deployment from the Basic sample unless I
provide an existing deployment. Test the agent locally, deploy it to Foundry
Agent Service, and invoke it with: "Write a haiku about deploying cloud
applications."

当 MCP 工具可用时，编码代理应检查可用的 Foundry 工具，加载托管代理快速启动工作流，并请求或默认缺失值，例如订阅、区域、项目名称以及是否使用现有的 Foundry 项目。

步骤 3：查看和批准计划

查看编码代理建议的计划、文件、命令、Azure资源和角色分配。
若要与本快速入门保持一致，请选择 Python 3.13、Agent Framework、响应 API、基本示例代码和代码部署。
仅在验证订阅、区域、资源组、模型部署和配额后才批准创建成本资源。
如果编码代理要求你进行身份验证，请你自己运行 az login 和 azd auth login，然后让编码代理继续。

步骤 4：让技能搭建基架，并测试智能体

让编码代理创建托管代理项目，在选择新的 Foundry 项目时预配资源，编写本地环境值，准备本地环境，并运行本地冒烟测试。对于 Python 代理，技能工作流会在首次本地运行时使用 azd ai agent run 安装依赖项。

工作流还应添加编码代理主机所需的项目指导文件，并在本地测试之前检查生成的项目配置。

如果编码代理主机无法保留运行冒烟测试的本地服务器，请使用本文中的“Azure开发人员 CLI”选项卡获取本地测试命令。只有在决定远程验证代理之后，才能继续部署。

步骤 5：部署和调用托管代理

本地冒烟测试成功后，请让编码代理完成部署和远程验证：

Continue with the Microsoft Foundry Skill workflow. Deploy the hosted agent to
Foundry Agent Service, show the deployment status and playground link, and invoke
it remotely with: "Write a haiku about deploying cloud applications." If the
skill workflow requires evaluation suite generation before the final summary,
submit the generation job and show me the follow-up eval command.

工作流完成后，编码代理应显示托管代理名称、版本、部署状态、终结点、操场链接、已创建的资源、对测试提示的响应以及任何评估跟进命令。

清理资源

完成后删除资源，以便停止产生费用。

警告

azd down 永久删除资源组中的每个资源，包括 Foundry 项目、模型部署、容器注册表、Application Insights 和托管代理。如果预配到包含其他资源的资源组中， azd down 也会删除这些资源。

azd down

azd 列出它删除的资源并提示进行确认。清理大约需要 2-5 分钟。

打开Azure门户，转到包含代理的资源组。
选择 “删除资源组”，键入要确认的资源组名称，然后选择“ 删除”。

警告

删除资源组会永久删除其中的所有内容，包括 Foundry 项目、容器注册表、Application Insights 和托管代理。

Microsoft Foundry 技能本身不会删除资源。它可以帮助你的编码代理识别本快速入门创建的资源，并选择正确的清理方法。查看并批准后，你或你的编码代理仍运行清理命令。

在托管代理项目文件夹中，要求编码代理查看清理：

Use the Microsoft Foundry Skill to identify the Azure resources created for
this quickstart. Confirm whether azd down is the right cleanup method for
this project, and show me the resources before any deletion command runs.

如果托管代理项目是使用 azd 创建的，并且资源组仅包含快速入门资源，请运行：
```
azd down
```
仅在验证命令列出的资源组和资源后批准删除。

如果编码代理无法运行清理命令，请使用本文中的Azure开发人员 CLI 选项卡，或者从 Azure 门户中删除资源组。

故障排除

问题	解决方案
`SubscriptionNotRegistered`	注册提供程序：`az provider register --namespace Microsoft.CognitiveServices`。
预配期间 `AuthorizationFailed`	请求订阅或资源组的参与者角色。
`AuthenticationError` 或 `DefaultAzureCredential` 失败	若要刷新凭据，请先运行 `azd auth logout`，然后运行 `azd auth login`。
`ResourceNotFound` 或 `DeploymentNotFound`	在 Foundry 门户的构建>部署下验证终结点 URL 和模型部署名称。
`create_version_from_code` 与 `Hosted agent provisioning failed` 冲突	检查 `main.py` 和 `requirements.txt` 是否位于您上传的 zip 文件的根目录中，并验证 `.env` 中的模型部署名称是否存在于目标 Foundry 项目中。
`Connection refused` 在本地运行中	确保没有其他进程使用端口 8088。
`azd ai agent init` 失败	运行 `azd version` 以验证 1.25.0 或更高版本。使用 `winget upgrade Microsoft.Azd` （Windows）或 `brew upgrade azd` （macOS）进行更新。运行 `azd ext list` 并升级代理扩展 `azd ext upgrade azure.ai.agents` ，以获取 0.1.34 预览版或更高版本。
未找到 Microsoft Foundry Toolkit 扩展	从市场安装 Microsoft Foundry Toolkit for Visual Studio Code，并切换到预发行版通道。
编码代理不会加载 Microsoft Foundry 技能	按照在编码代理中使用 Microsoft Foundry 技能中的说明安装或重新加载该技能。
代码代理无法运行本地冒烟测试	使用本文中的Azure开发人员 CLI 或 VS Code 选项卡进行本地测试。仅在查看本地验证不可用的原因后继续远程验证。
在 Windows ARM64 上本地运行失败，并出现与 `aiohttp`、`grpcio`、`cryptography` 或 `httptools` 相关的构建错误	预生成的 arm64 轮未针对这些包发布，并且源生成需要Microsoft C++ 生成工具。作为一种临时解决方法，请跳过步骤 3，然后先使用`azd deploy`，再使用`azd ai agent invoke`远程验证代理。

有关完全权限和角色分配矩阵，请参阅托管代理权限参考。

你学到的内容

在本快速入门中，您将：

从基本代理示例搭建托管代理项目基架。
使用 Python SDK 上传并路由托管代理版本，或使用 Azure 开发人员 CLI 为示例搭建基架。
在本地测试代理。
将智能体部署到 Foundry 智能体服务。
从 Python SDK、Azure开发人员 CLI、VS Code 或使用 Microsoft Foundry 技能的编码代理发送测试提示。

后续步骤

生成工具箱并将其与托管代理一起使用

反馈

此页面是否有帮助？

Last updated on 2026-07-14

快速启动：部署第一个托管代理

先决条件

步骤 1：初始化示例代理

步骤 2：预配Azure资源

步骤 3：在本地测试代理

步骤 4：部署到 Foundry 智能体服务

步骤 5：调用代理

步骤 1：创建或选择 Foundry 项目

步骤 2：下载基本示例代理代码

步骤 3：创建Python环境和配置设置

步骤 4：使用 Python 部署托管代理

步骤 5：调用代理

步骤 1：创建 Foundry 项目

步骤 2：部署模型

步骤 3：创建托管代理项目

步骤 4：安装依赖项

步骤 5：在本地测试代理

步骤 6：部署到 Foundry 智能体服务

步骤 7：调用代理

步骤 1：使用 Foundry 技能打开工作区

步骤 2：请求技能创建托管智能体

步骤 3：查看和批准计划

步骤 4：让技能搭建基架，并测试智能体

步骤 5：部署和调用托管代理

清理资源

故障 排除

你学到的内容

后续步骤

相关内容

反馈

其他资源

故障排除