用 Azure Developer CLI 在本地运行托管代理

#用 Azure Developer CLI 在本地运行托管代理

使用 azd ai agent run 在本机启动 Microsoft Foundry 托管代理（hosted agent），并用 azd ai agent invoke --local 在不部署到 Azure 的情况下测试它。你还会学到如何设置端口、在多代理项目中选择一个代理、覆盖启动命令，以及传入本地运行时密钥（secret）。

如果使用 GitHub Copilot 这类编码代理，Microsoft Foundry Skill 可以在部署前帮助配置本地启动、端口、密钥和测试命令。

先决条件

• 一个已初始化的托管代理项目。创建方法参见初始化代理项目。
• 已安装 azd Foundry 扩展。安装步骤参见安装 azd Foundry 扩展。
• 已认证的 Azure Developer CLI（azd）会话。需要时运行 azd auth login。
• 代理所需的语言运行时，例如 Python 3.10+、.NET 8+ 或 Node.js。

启动代理

• 在项目目录中启动代理：

    azd ai agent run

该命令自动检测项目类型（Python、.NET、Node.js），安装依赖，并在 localhost:8088 上启动代理服务器。启动命令读取自 azure.yaml 中的 startupCommand 属性。

提示

azd ai agent run 会自动注入默认 azd 环境 中的环境变量（environment variable），也就是你用 azd env select 选定、或在 azd ai agent init 期间创建的那个环境。因此 FOUNDRY_PROJECT_ENDPOINT、AZURE_SUBSCRIPTION_ID，以及用 azd env set 设置的任何值，都可以在不手工配置的情况下提供给代理。

完整列表参见为托管代理配置环境变量。

在自定义端口上启动

• 默认端口不可用时传入 --port：

    azd ai agent run --port 9090

启动指定代理

• 如果项目定义了多个代理，指定要运行的那一个：

    azd ai agent run my-agent

覆盖启动命令

• 传入 --start-command 以覆盖 azure.yaml 中的命令：

    azd ai agent run --start-command "python app.py"

该命令覆盖 azure.yaml 服务配置中定义的 startupCommand。startupCommand 既是本地开发（azd ai agent run）的默认命令，也是部署后容器启动所用的命令。更多信息参见 azure.yaml 服务配置。

传入环境变量和密钥

本地运行会读取 azure.yaml 里 azure.ai.agent 服务中声明的 env 映射，并从当前 azd 环境解析其中的 ${VAR} 占位符。要提供某个值（例如 API 密钥），把它设为 azd 环境变量，并在 azure.yaml 中引用。

1. 在当前 azd 环境中设置取值：

    azd env set OPENAI_KEY <value>

azd 把环境值存放在 .azure/<env>/.env。.azure 目录默认被 Git 忽略，因此这些值不会进入源代码管理。

2. 在 azure.yaml 的 azure.ai.agent 服务中引用该变量，以便本地运行把它注入进去：

    services:
      my-agent:
        host: azure.ai.agent
        env:
          OPENAI_KEY: ${OPENAI_KEY}

对于完全不应放在本地 .env 文件中的密钥，把它们存放在 Foundry 项目连接（project connection）中，并在 env 映射里用 ${{connections.<name>.credentials.<field>}} 占位符引用。平台在运行时解析该占位符。更多信息参见为托管代理配置环境变量。

用 invoke 测试

• 另开一个终端，向正在运行的代理发送一条消息：

    azd ai agent invoke --local "Hello, what can you do?"

--local 标志把请求发到 localhost:8088，而不是已部署的终结点（endpoint）。

用 invoke 测试协议

代理使用的协议定义在 azure.yaml 里 azure.ai.agent 服务的 protocols 字段中。如果代理实现了 responses 协议，invoke 会发送标准的 Responses API 请求。如果代理使用 invocations 协议，载荷就是代理代码所期望的内容。使用 --input-file（-f）发送自定义 JSON 正文：

azd ai agent invoke --local -f request.json

对于 invocations 代理，参阅示例的 README，或检查处理程序或入口点，以了解期望的载荷结构。

如果代理实现了多个协议，invoke 默认使用 responses 协议。传入 -p（--protocol），取值为 responses 或 invocations，即可显式选择其一：

azd ai agent invoke --local --protocol invocations -f request.json

用 curl 测试

• 直接用 curl 测试：

    curl -X POST http://localhost:8088/responses \
       -H "Content-Type: application/json" \
       -d '{"input": "Hello, what can you do?"}'

排查本地开发问题

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/run-hosted-agent-locally