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

快速入门：部署第一个托管代理

在本快速入门中，你将使用 Foundry 工具将容器化 AI 代理部署到 Foundry 代理服务。 示例代理使用 Web 搜索和（可选）模型上下文协议（MCP）工具来回答问题。 最终，你将会拥有一个正在运行的托管代理，可以通过 Foundry Playground 进行交互。 选择首选的部署方法以开始使用。

在本快速入门中，你将：

  • 使用 Foundry 工具设置代理示例项目
  • 在本地测试代理
  • 部署到 Foundry 代理服务
  • 在试验场中与你的代理交互
  • 清理资源

先决条件

在开始之前，需要：

注释

托管代理目前正处于预览阶段。

所需权限

需要在项目范围内使用 Azure AI 项目经理来创建和部署托管代理。 此角色包括创建代理的数据平面权限，以及将 Azure AI 用户角色分配给平台创建的代理标识的功能。 代理标识需要在项目中使用 Azure AI 用户在运行时访问模型和项目。

如果使用 azd 或 VS Code 扩展，则工具会自动处理大多数 RBAC 分配，包括：

确保您使用的 Azure 容器注册表中，Foundry 项目的托管标识具有 ACR 拉取角色。 如果你喜欢拥有所有者或“用户访问管理员”访问权限，则工具 azd/vscode 也可以为你执行此分配。 用于平台生成的代理身份标识的 Azure AI 用户（用于运行时模型和工具访问）

步骤 1：配置示例项目

警告

本文档适用于新后端上的托管代理，需要 azd ai agent version 0.1.27-preview 或更高版本。 对于使用 Azure 容器应用的旧体验，请继续使用 0.1.25 预览版。

安装Azure开发人员 CLI 代理扩展并初始化新的托管代理项目。

  1. 为 Azure 开发人员 CLI 安装 ai agent 扩展：

    azd ext install azure.ai.agents

    若要验证是否已安装扩展，请运行：

    azd ext list

  2. 在空目录中初始化新的托管代理项目：

    azd ai agent init

    交互式流将引导你完成以下配置：

    • 语言 - 选择您希望示例代码使用的编程语言：C# 或 Python。
    • 代理模板 - 选择要开始使用的示例。
    • 模型配置 - 选择在 Foundry 中部署新模型或使用现有 Foundry 项目中的现有模型。
    • Azure 订阅 — 选择要在其中创建 Foundry 资源的订阅。
    • 位置 - 为资源选择一个区域。
    • 模型 SKU - 选择适用于你的区域和订阅的 SKU。
    • 部署名称 - 输入模型部署的名称。
    • 容器大小 - 选择 CPU 和内存分配或接受默认值。

    重要

    如果选择了包含工具且未使用 MCP 服务器的示例，请注释掉或删除 agent.yaml 文件中的以下行：

    - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
  value: <CONNECTION_ID_PLACEHOLDER>

    小窍门

    如果在非交互式环境中（如 CI/CD 管道或 SSH 会话）中运行，请使用 --no-prompt 标志和 azd ai agent init. 还必须将所有必需值作为命令行标志提供，而不是响应交互式提示。

  3. 预配所需的Azure资源：

    注释

    需要Azure订阅的Contributor权限才能进行资源预配。

    azd provision

    此命令需要几分钟时间，并创建以下资源：

    资源 目的 成本
    资源组 在同一区域中组织所有相关资源 免费
    模型部署 代理使用的模型 请参阅 Foundry 定价
    铸造厂项目 托管代理并提供 AI 功能 基于使用量的；请参阅 Foundry 定价
    Azure 容器注册表 存储您的代理容器镜像 基本层;请参阅 ACR 定价
    Log Analytics工作区 在一个位置管理所有日志数据 无直接成本。 请参阅 Log Analytics 成本
    Application Insights 监视代理性能和日志 按需付费;请参阅 Azure Monitor 定价
    托管标识 对您的代理进行身份验证以访问Azure服务。 免费

    小窍门

    完成本快速入门后，运行 azd down 以删除资源并停止产生费用。

步骤 2：在本地测试代理

在部署之前，请在本地验证代理是否正常工作。

  1. 在本地启动代理：

    azd ai agent run

    此命令会自动设置环境、安装依赖项并启动代理。 它使用在 startupCommand 中定义的 azure.yaml 来启动代理。

    注释

    预览包可以在安装过程中生成 pip 依赖项版本冲突警告。 这些警告是非阻塞性的 — 代理能够启动并正确响应，即使有这些警告。

    如果代理无法启动，请检查以下常见问题：

    错误 解决方案
    AuthenticationError 或 DefaultAzureCredential 失败 运行 azd auth logout 并 azd auth login 刷新会话。
    ResourceNotFound 验证终结点 URL 是否与 Foundry 门户中的值匹配。
    DeploymentNotFound 检查 构建>部署中的部署名称。
    Connection refused 确保没有其他进程使用端口 8088。

  2. 在单独的终端中，将测试消息发送到本地代理。

    对于使用响应 API 的代理，可以将字符串作为有效负载发送：

    azd ai agent invoke --local "What is Microsoft Foundry?"

    对于使用 Invocations API 的代理，请检查 README.md 以获取预期的有效负载。 这些示例通常需要一个 JSON 负载，但请检查 README.md 中的内容以获取具体示例：

    您将会看到来自代理的响应。

步骤 3：部署到 Foundry 代理服务

由于已在步骤 1 中预配基础结构，请将代理代码部署到Azure：

azd deploy

代理容器是远程生成的，因此计算机上不需要 Docker Desktop。

注释

该 azd deploy 命令将 Azure RBAC 角色分配给代理的代理标识。 除了预配所需的参与者角色之外，此角色分配还需要订阅的所有者或用户访问管理员权限。

警告

部署期间，托管代理会产生费用。 完成测试后，完成 清理资源 以删除资源并停止费用。

完成后，输出显示智能体演练场链接和以编程方式调用智能体的终结点：

Deploying services (azd deploy)

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

重要

请确保在 VS Code 中使用 Microsoft Foundry Toolkit 扩展和 Foundry 扩展的预发行版本。

在 VS Code 扩展页中，选择 Foundry Toolkit 扩展和 Foundry 扩展并切换到预发行版本。

步骤 1：创建 Foundry 项目

使用 VS Code 中的 Microsoft Foundry Toolkit 扩展创建新的 Microsoft Foundry 项目资源。

  1. 打开命令面板（Ctrl+Shift+P），然后选择Microsoft Foundry：创建Project。

  2. 选择Azure订阅。

  3. 创建新的资源组或选择现有资源组。

  4. 输入 Foundry Project 资源的名称。

项目创建完成后，继续执行下一步并部署模型。

步骤 2：部署模型

使用 VS Code 中的 Microsoft Foundry Toolkit 扩展将模型部署到 Foundry。

  1. 打开命令面板（Ctrl+Shift+P），然后选择Microsoft Foundry：打开模型目录。

  2. 浏览模型目录或搜索 gpt-4.1 并选择“ 部署 ”按钮。

  3. 在“模型部署”页中，选择 部署到 Microsoft Foundry 按钮。

成功部署模型后，继续执行下一步并创建托管代理项目

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

使用 VS Code 中的 Microsoft Foundry Toolkit 扩展为新的托管代理项目搭建基架。

  1. 打开命令面板（Ctrl+Shift+P），然后选择Microsoft Foundry：创建新的托管代理。

  2. 选择要使用的框架。

  3. 选择编程语言、Python或 C# 。

  4. 选择“响应 API”或“调用 API”。

  5. 选择要使用的示例代码。

  6. 选择要在其中保存项目文件的文件夹。

  7. 输入托管代理的名称。

新的 VS Code 窗口将以新的代理项目文件夹作为活动工作区启动。

步骤 4：安装依赖项

建议使用虚拟环境来隔离项目依赖项：

macOS/Linux：

python -m venv .venv
source .venv/bin/activate

Windows （PowerShell）：

python -m venv .venv
.\.venv\Scripts\Activate.ps1

安装依赖项

使用 pip 安装所需的Python依赖项：

pip install -r requirements.txt

有关所需包的列表，请参阅 requirement.txt。

步骤 5：在本地测试代理

在部署之前运行并测试代理。

在 VS Code 中按 F5 开始调试。 或者，可以使用 VS Code 调试菜单：

  1. 打开 “运行和调试 ”视图（Ctrl+Shift+D / Cmd+Shift+D）
  2. 从下拉列表中选择“调试本地工作流 HTTP 服务器”
  3. 单击绿色 的“开始调试 ”按钮（或按 F5）

这将：

  1. 在启用调试的情况下启动 HTTP 服务器
  2. 打开 Foundry Toolkit 代理检查器进行交互式测试
  3. 允许设置断点并检查工作流

选项 2：在终端中运行

以 HTTP 服务器身份运行（默认值）：

python main.py

这将在http://localhost:8088/本地启动托管代理。

PowerShell （Windows）：

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl （Linux/macOS）：

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

代理将使用该工具 get_available_hotels 搜索与条件匹配的可用酒店。

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

直接从 VS Code 部署代理。

  1. 打开命令面板（Ctrl+Shift+P），然后选择Microsoft Foundry：部署托管代理。

  2. 选择“默认 ACR”

  3. 选择托管代理容器的 CPU 和内存配置。

通过选择左侧的图标切换到 Microsoft Foundry Toolkit 资源管理器。 部署完成后，代理会显示在 “托管代理”（预览） 树视图边栏中。

验证并测试代理

部署完成后，验证代理是否正在运行。

检查代理状态

检查你的智能体状态以确认其正在运行。

  1. 请从“托管代理（预览）”树视图中选择您的代理。

  2. 选择刚刚部署的代理

详细信息页显示“容器详细信息”部分下的“状态”。

使用 VS Code 在操场中进行测试

适用于 VS Code 的 Microsoft Foundry Toolkit 包括一个集成的交互环境，用于聊天和与智能助手交互。

  1. 请从“托管代理（预览）”树视图中选择您的代理。

  2. 选择 Playground 选项并键入消息并发送以测试代理。

验证代理状态

检查已部署代理的状态：

azd ai agent show

若要以表格式显示输出，请执行以下操作：

azd ai agent show --output table

如果项目有多个代理服务，请将代理名称指定为位置参数：

azd ai agent show <agent-name>

小窍门

在<agent-name>分区下的azure.yaml文件中查找services:。

测试已部署的代理

使用前面使用的相同 invoke 命令将测试消息发送到已部署的代理，但没有 --local 标志：

对于使用响应 API 的代理，可以将字符串作为有效负载发送：

azd ai agent invoke <payload>

几秒钟后，应会看到来自代理的响应。

查看代理日志

监视代理的实时日志：

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

如果项目有多个代理服务，请将代理名称指定为位置参数：

azd ai agent monitor <agent-name> --follow

在 Foundry 沙盒环境中进行测试

在 Foundry 门户中导航到智能体：

  1. 打开 Foundry 门户并使用Azure帐户登录。

  2. 从 Recent projects 列表中选择项目，或选择所有项目来找到它。

  3. 在左侧导航中，选择“ 生成 ”以展开菜单，然后选择 “代理”。

  4. 在代理列表中，找到已部署的代理（它与部署中的代理名称匹配）。

  5. 选择代理名称以打开其详细信息页，然后在顶部工具栏中选择在 Playground 中打开。

  6. 在聊天界面中，键入一条测试消息，如“What is Microsoft Foundry？”，然后按 Enter。

  7. 验证代理是否响应来自 Web 搜索结果的信息。 当代理查询外部源时，响应可能需要几秒钟时间。

小窍门

如果操场未加载或代理未响应，请使用上面所述的“容器详细信息”页验证代理状态是否 Started。

清理资源

若要避免产生费用，请删除完成后的资源。

警告

此命令永久删除资源组中的所有Azure资源，包括 Foundry 项目、模型部署、容器注册表、Application Insights 和托管代理。 此操作不能撤消。 如果你使用包含其他资源的现有资源组，请谨慎 — azd down 会删除组中的所有内容，而非仅本快速入门创建的资源。

若要预览将删除的内容，请 down 运行以下命令：

azd down

完成后， azd 会显示将删除的所有资源，并提示你进行确认。 选择 yes 以继续或 no 取消。

清理过程大约需要 2-5 分钟。

警告

删除资源会永久删除在本快速入门中创建的所有Azure资源，包括 Foundry 项目、容器注册表、Application Insights 和托管代理。 此操作不能撤消。

若要删除资源，请打开 Azure 门户，导航到资源组，并将其连同所有包含的资源一起删除。

若要验证资源是否已删除，请打开 Azure 门户，转到资源组，确认资源不再显示。 如果资源组为空，也可以将其删除。

故障排除

如果遇到问题，请尝试以下解决方案来解决常见问题：

問题 解决方案
SubscriptionNotRegistered 个错误 注册提供者：az provider register --namespace Microsoft.CognitiveServices
预配期间 AuthorizationFailed 请求订阅或资源组的参与者角色。
代理未在本地启动 验证环境变量是否已设置并运行 az login 以刷新凭据。
AcrPullUnauthorized 个错误 向容器注册表上项目的托管标识授予 AcrPull 角色。

有关托管代理部署中涉及的所有权限和角色分配的完整详细信息，请参阅 托管代理权限参考。

問题 解决方案
azd ai agent init 失败 运行 azd version 以验证版本 1.24.0+。 使用 winget upgrade Microsoft.Azd （Windows） 或 brew upgrade azd （macOS） 进行更新。 验证是否已安装 azd ext list代理扩展。 请确保具有最新版本的扩展 azd ext upgrade azure.ai.agents，版本为 0.1.27-preview 或更高版本。

查看代理的容器日志

可以检查容器的控制台和系统日志来排查问题。

  1. 请从“托管代理（预览）”树视图中选择您的代理。

  2. 选择托管代理的“Playground”选项卡

  3. 在会话详细信息中选择“日志”部分。

查看代理的会话文件

可以查看存储在基于 ADC 的代理的主目录中的所有文件

  1. 在“托管代理（预览）”树状视图中选择您的托管代理。

  2. 选择托管代理的“Playground”选项卡

  3. 在会话详细信息中选择“files”部分。

您可以在当前文件夹中下载、上传和创建文件夹，单击文件夹将进入该文件夹，而单击顶部导航栏将返回上级。

問题 解决方案
找不到扩展 从 VS Code 市场安装 Microsoft Foundry Toolkit for VS Code 扩展 。

已了解的内容

在本快速入门中，请执行以下操作：

  • 使用 Foundry 工具设置托管代理示例（Web 搜索和 MCP）
  • 在本地测试代理
  • 部署到 Foundry 代理服务
  • 在 Foundry 试验场中验证了你的代理

后续步骤

现在你已部署了第一个托管代理，了解如何：

管理托管代理生命周期

为您的代理添加附加功能：

可以在 工具目录 文章中看到可用工具的完整列表。

相关内容

  • Last updated on