# 将基于 Markdown 的代理部署到 Azure Functions 此技能将基于本地声明性 Markdown 的代理项目转换为可部署的 Azure Functions 应用程序。转换后的应用程序遵循 [functions-markdown-agent 示例]() 的结构。用户运行“azd up”进行部署。 ## 何时使用 * 用户有一个“AGENTS.md”文件并希望在云中运行他们的代理 * 用户希望与他们的团队共享当地的 Copilot 代理 * 用户想要部署代理作为 HTTP API 或 MCP 服务器 * 用户询问有关在 Azure 上托管 Markdown 代理的问题 ## 参考：目标项目结构支持两种布局。根据用户现有项目进行选择。 ### 布局 A：`src/` 子文件夹（默认 — 与示例存储库匹配）当代理项目可以位于专用的“src/”子文件夹中时使用。这是代理代码和基础设施之间最清晰的分离。 <项目根目录>/ ├── azure.yaml # azd 项目定义 ├── 下文/ │ ├── main.bicep # 主要二头肌模板 │ ├── main.parameters.json # 二头肌参数 │ ├── abbreviations.json # 资源命名缩写 │ ├── 应用程序/ │ │ ├── api.bicep # 函数应用定义 │ │ ├── rbac.bicep # 角色分配 │ │ ├── Foundry.bicep # AI Foundry模型部署 │ │ ├── vnet.bicep # 可选VNet │ │ └── storage-PrivateEndpoint.bicep │ ├── 挂钩/ │ │ └── prepackage.sh # 复制 src → infra/tmp 进行打包 │ └── assets/ # 打包时合并的运行时资源（从示例仓库复制，请勿修改） │ └── （host.json、function_app.py 等 — 与用户的代理项目分开维护） └── src/ # 代理项目 — 纯 Copilot 项目，无云代码 ├── AGENTS.md # 代理指令+可选的YAML frontmatter ├── .github/ │ └── Skills/ # 特工技能（每个技能都是一个带有SKILL.md的文件夹） │ └── <技能名称>/ │ └── 技能.md ├── .vscode/ │ └── mcp.json # MCP 服务器配置（仅适用于云的远程/HTTP） ├──tools/ # 自定义Python工具（简单功能，无需框架） │ └── <工具名称>.py └──requirements.txt # 自定义工具的Python依赖 ### 布局 B：根布局当代理项目已位于存储库根目录时使用（例如，用户的“AGENTS.md”、“.github/skills/”、“.vscode/mcp.json”位于顶层）。 `infra/` 和 `azure.yaml` 与现有代理文件一起添加。 <项目根目录>/ ├── AGENTS.md # 代理指令+可选的YAML frontmatter ├── .github/ │ └── 技能/ # 特工技能 │ └── <技能名称>/ │ └── 技能.md ├── .vscode/ │ └── mcp.json # MCP 服务器配置（仅适用于云的远程/HTTP） ├── tools/ # 自定义Python工具 │ └── <工具名称>.py ├──requirements.txt # 自定义工具的Python依赖 ├── azure.yaml # azd 项目定义 └── infra/ # 基础设施（为部署而添加） ├── 主.二头肌 ├── main.parameters.json ├── 缩写.json ├── 应用程序/ │ ├── api.bicep │ ├── rbac.bicep │ ├── 铸造厂.bicep │ ├── vnet.bicep │ └── storage-PrivateEndpoint.bicep ├── 挂钩/ │ └── prepackage.sh # 复制根代理文件 → infra/tmp 进行打包 └── assets/ # 运行时资源（从示例存储库复制，请勿修改） └──（host.json、function_app.py 等） ## 分步转换说明 ### 第 1 步：分析用户现有项目检查用户的工作空间： 1. **`AGENTS.md`** — 代理的指令。这是必需的。 2. **技能** — 可能位于 `.github/skills/`、`skills/` 或其他位置。 3. **`mcp.json`** — 可能位于 `.vscode/mcp.json` 或其他地方。查找 MCP 服务器定义。 4. **工具或脚本** — 代理依赖的任何自定义代码。 5. **任何现有的 Azure 配置** - Bicep、ARM 模板、terraform 等。如果找到，请警告用户示例存储库中的“infra/”目录将替换任何现有基础设施。在继续之前备份或重命名现有的“infra/”目录。如果没有“AGENTS.md”，请要求用户提供一个或帮助他们创建它。 **选择布局**： * 如果代理文件（`AGENTS.md`、`.github/skills/`、`.vscode/mcp.json`、`tools/`）已经位于存储库根目录并且用户希望将它们保留在那里 → 使用**布局 B（根目录）**。 * 如果重新开始或用户喜欢干净的分离 → 使用**布局 A（`src/` 子文件夹）**。 * 如果有疑问，当用户在根目录下已有代理文件时，首选布局 B（根目录），以最大程度地减少干扰。 ### 第 2 步：创建项目结构从[示例存储库]() 搭建部署基础结构。 **如何获取示例存储库文件**：使用“git clone https://github.com/Azure-Samples/functions-markdown-agent.git”将存储库克隆到临时目录中，或使用 GitHub 工具（例如“mcp_github-mcp_get_file_contents”）来获取单个文件。 1. 从示例存储库复制“azure.yaml” - 调整“name”字段以匹配用户的项目名称。对于 **根布局** ，您还需要修改后的 `prepackage.sh` （请参阅步骤 8）。 2. 从示例存储库复制整个 `infra/` 目录，包括： * `infra/main.bicep`, `infra/main.parameters.json`, `infra/abbreviations.json` * `infra/app/` （所有 `.bicep` 文件：`api.bicep`、`rbac.bicep`、`foundry.bicep`、`vnet.bicep`、`storage-PrivateEndpoint.bicep`） * `infra/hooks/prepackage.sh` （将被替换为根布局 - 参见步骤 8） * `infra/assets/` — 这些是运行时文件（例如，`function_app.py`、`host.json`、`package.json`、`copilot_shim/`、`public/`、`.funcignore`、`extra-requirements.txt`）。它们是部署所必需的，并且必须从示例存储库中复制。用户不应修改这些文件。 * 不要**复制 `infra/main.json` — 它是重新生成的已编译的 ARM 模板。 3. 对于 **布局 A (`src/`)**：创建 `src/` 目录并在其中放置代理文件。 4. 对于**布局 B（根）**：代理文件保留在存储库根目录中 - 不需要 `src/` 目录。 5. 基础设施通常不需要修改，除非代理需要访问其他 Azure 资源（请参阅步骤 6 添加角色分配）。 ### 步骤 3：放置 AGENTS.md * **布局 A** ：将用户的 `AGENTS.md` 复制或移动到 `src/AGENTS.md` 中。 * **布局 B** ：将 `AGENTS.md` 保留在项目根目录下。 #### YAML 前沿问题添加 YAML frontmatter（如果尚不存在）。 frontmatter 是可选的，但推荐： --- 名称：<代理名称> 描述：<代理做什么的简要描述> --- #### 定时器触发器（可选）如果用户想要计划/自主代理运行，请在 frontmatter 中添加一个 `functions` 数组： --- 名称：我的代理描述：我的代理描述功能： - 名称：上午简报触发：定时器时间表：“0 0 8 * * *” 提示：“检查最新的构建状态并总结任何新的关键问题。” --- 计时器触发器的 Frontmatter 字段： * `name` — 可选（如果省略则自动生成） * `trigger` — 必须是 `timer` （当前仅支持触发器类型） * `schedule` — 必需，NCRONTAB 表达式 (`{秒} {分钟} {小时} {天} {月} {星期}`) * `prompt` — 必填，每次触发时发送给代理的提示 * `logger` — 可选，默认为 `true`。启用后，记录完整的代理输出，包括 session_id、响应、tool_calls **注意** ：仅支持“trigger:timer”。其他触发器类型将在启动时被拒绝。这对于执行定期任务（例如检查构建状态、发送报告、监控系统等）的代理非常有用。 ### 第四步：移动技能技能必须位于 `.github/skills//SKILL.md` 中（相对于代理项目根目录 — 对于布局 A 为“src/.github/skills/”，对于布局 B 为“.github/skills/”）。 * 如果用户的技能位于不同位置，请移动它们。 * 每个技能都是一个至少包含“SKILL.md”文件的文件夹。 * 文件夹名称必须与 SKILL.md frontmatter 中的“name”字段匹配。 * 技能还可以包含 `references/` 和 `assets/` 子目录。 #### 回顾和清理技能当部署到 Azure Functions 时，技能在云环境中运行，无需 shell 访问。查看每项技能并应用这些规则： 1. **删除执行 shell 命令或任意代码的指令。** 技能不得告诉代理运行 shell 命令（例如“bash”、“curl”、“python”、“npm”、“git”）、执行脚本或调用命令行工具。任何此类功能都必须转换为“tools/”中的 Python 工具（请参阅步骤 6）。 2. **匿名 GET 请求是可以的。** 技能可以指示代理使用 HTTP GET 从可公开访问的 URL 获取数据（例如，“从 `https://prices.azure.com/api/retail/prices?...` 获取 JSON”）。这是可行的，因为代理运行时支持直接获取 URL。 3. **非 GET HTTP 方法 → Python 工具。** 如果技能指示代理发出 POST、PUT、PATCH 或 DELETE 请求，请将该逻辑转换为“tools/”中的 Python 工具。该工具应使用“httpx”或“requests”进行调用，并且技能应按名称引用该工具。 4. **删除`scripts/`目录。**如果技能包含包含可执行代码（bash、Python等）的`scripts/`文件夹，请将这些脚本转换为`tools/`中的Python工具。从技能中删除 `scripts/` 目录 - 它不会在云端执行。 5. **技能 frontmatter 中的“allowed-tools”。**如果技能的 frontmatter 有引用“Bash(*)”、shell 命令或其他本地执行工具的“allowed-tools”，请删除这些条目。替换为对“tools/”中创建的相应 Python 工具的引用。 **转换示例**：如果技能显示“运行 `curl -X POST https://api.example.com/data -d '{...}'`”，则创建一个 Python 工具： # 工具/example_api.py 导入httpx 从 pydantic 导入 BaseModel、Field 类 PostDataParams(BaseModel): 有效负载：str = Field（描述=“要发送的JSON有效负载”） async def post_to_example_api(params: PostDataParams) -> str: """将数据发布到示例 API。""" 与 httpx.AsyncClient() 异步作为客户端：响应 = 等待 client.post("https://api.example.com/data", content=params.payload, headers={"Content-Type": "application/json"}) 返回响应.文本然后将技能说明更新为：“使用 **post_to_example_api** 工具向 API 发送数据。” ### 步骤 5：处理 MCP 服务器将 MCP 配置放在“.vscode/mcp.json”中（相对于代理项目根目录 — 对于布局 A 为“src/.vscode/mcp.json”，对于布局 B 为“.vscode/mcp.json”）。 **重要提示：云部署仅支持远程（基于 HTTP）MCP 服务器。** 远程 MCP 服务器的格式： { “服务器”：{ “服务器名称”：{ "url": "https://example.com/api/mcp", “类型”：“http” } } } #### 处理本地 MCP 服务器如果用户的“mcp.json”包含本地 MCP 服务器（例如“stdio”类型、“基于命令”、“基于 npx”），则警告他们： > **警告**：本地 MCP 服务器（基于 stdio/命令）在部署到 Azure Functions 时将无法工作。云中仅支持基于 HTTP 的远程 MCP 服务器。考虑以下选项之一： > > 1. 查找并使用 MCP 服务器的远程/托管版本 > 2. 将 MCP 服务器的功能转换为 `tools/` 中的 Python 工具（参见步骤 6） > 3. 将本地服务器保留在`mcp.json`中以供本地开发，但在云端会被忽略 > 将本地 MCP 服务器转换为 Python 工具时： 1. 识别MCP服务器提供的工具/功能 2. 在`tools/`中创建等效的Python函数 3.代理运行时将自动发现并将它们注册为工具 ### 第 6 步：创建 Python 工具对于代理所需的任何自定义功能（尤其是从本地 MCP 服务器迁移时），请在“tools/”中创建 Python 工具文件（对于布局 A，该文件为“src/tools/”；对于布局 B，该文件位于根目录下的“tools/”）。 #### 工具文件结构 `tools/` 中的每个 `.py` 文件应包含： 1. 用于类型化参数的 Pydantic `BaseModel` 2. 一个接受 params 模型并返回字符串的异步函数 3. 清晰的文档字符串（成为工具描述）从 pydantic 导入 BaseModel、Field 类 MyToolParams(BaseModel)： param1: str = Field(description="param1 的描述") param2: int = Field(description="param2 的描述") async def my_tool(params: MyToolParams) -> str: """此工具功能的描述。这成为工具描述。""" # 工具实现结果= f“用{params.param2}处理了{params.param1}” 返回结果 #### 工具发现规则 * 运行时在启动时扫描 `tools/*.py` * 排除以 _ 开头的函数 * 每个文件仅注册一个公共函数 - 将每个工具放入其自己的“.py”文件中 * 如果工具导入失败，运行时会记录错误并继续 * 函数文档字符串成为工具描述（后备：`Tool: `） * 自定义工具仅在云端运行 - 它们在本地 Copilot Chat 中不起作用 #### 从工具访问 Azure 资源如果工具需要访问 Azure 资源（Cosmos DB、存储、Key Vault 等），请将“DefaultAzureCredential”与托管标识结合使用 — 切勿对凭据进行硬编码。您还需要更新 Bicep 基础设施以部署资源、添加角色分配以及将端点作为应用程序设置传递。有关包含代码示例和 Bicep 模板的完整模式，请参阅 Azure 资源参考。 ### 步骤7：添加requirements.txt 使用自定义工具所需的依赖项创建“requirements.txt”（在布局 A 的“src/”中，或在布局 B 的项目根目录中）： # 仅当工具需要额外的依赖项时才需要派丹蒂克>=2.0.0 添加工具导入的任何其他包（例如“azure-identity”、“azure-cosmos”、“requests”、“httpx”等）。 ### 步骤 8：设置 azure.yaml 和 prepackage.sh 从示例存储库复制“azure.yaml”并调整“name”字段。两种布局的 `azure.yaml` 是相同的 - 有关确切内容，请参阅[模板]()。两种布局都使用“./infra/tmp”作为部署源。 `prepackage.sh` 钩子将代理文件 + 运行时资产组装到 `infra/tmp/` 中： * **布局 A** ：使用示例存储库中的默认“prepackage.sh”。它复制 `src/` → `infra/tmp/` 并合并 `infra/assets/`。 * **布局 B** ：将 `infra/hooks/prepackage.sh` 替换为从项目根目录复制的版本，跳过 `infra/`、`azure.yaml`、`.git/`、`.azure/` 等。有关两个完整脚本，请参阅[预打包脚本参考]()。 ### 步骤 9：设置 .gitignore 将条目添加到“.gitignore”（如果不存在则创建它，或合并到现有条目中）以排除 Python 字节码、venvs、Azure Functions 本地项目、机密、IDE 文件、“.azure/”、“tmp/”、“infra/main.json”和特定的“infra/assets/”子文件。有关完整的“.gitignore”模板，请参阅[模板参考]()。 ### 步骤10：验证和总结转换后，验证（路径相对于代理项目根 - 布局 A 的“src/”，布局 B 的存储库根）： * `AGENTS.md` 与代理指令一起存在 * 技能位于 `.github/skills//SKILL.md` * `.vscode/mcp.json` 仅包含远程 HTTP MCP 服务器（警告任何本地服务器） * 自定义工具位于“tools/”中，具有适当的 Pydantic 参数 + 异步函数 * `requirements.txt` 列出所有工具依赖项 * `azure.yaml` 位于项目根目录并具有正确的钩子 * `infra/hooks/prepackage.sh` 匹配所选的布局（从 `src/` 或根目录复制） * `infra/` 目录包含示例存储库中的所有 Bicep 文件和 `infra/assets/` * 如果工具访问 Azure 资源：使用 DefaultAzureCredential，角色分配位于 rbac.bicep 中告诉用户： 1. **部署**：运行“azd auth login”（如果尚未经过身份验证），然后从项目根目录运行“azd up” 2. **在部署期间** 系统将提示他们： * 蔚蓝位置 * 具有 Copilot 请求权限的 GitHub PAT（[在此处创建一个]()） * 模型选择（GitHub 模型如 `github:` 不需要额外的基础设施；Foundry 模型部署 AI Foundry 帐户） * 是否启用VNet集成 3. **部署后**： * 聊天 UI 位于根 URL：`https://.azurewebsites.net/` * 聊天 API：“POST /agent/chat”（JSON）和“POST /agent/chatstream”（SSE 流）。使用“x-ms-session-id”标头进行多轮对话。 * MCP 服务器：`/runtime/webhooks/mcp`（需要 `x-functions-key` 标头中的系统密钥 — 在 Azure 门户 > Function App > 应用程序密钥 > 系统密钥中找到它，或通过 `az functionapp keys list --name --resource-group --query systemKeys -o json` 找到它） 4. **本地开发** ：在 VS Code 中打开代理项目文件夹（布局 A 为 `src/`，布局 B 为 repo 根目录），启用 `chat.useAgentSkills`，并在 Copilot Chat 中与代理聊天（注意：`tools/` 中的 Python 工具仅在云部署后才能使用） ## 故障排除 * **单独使用`azd up`，而不是`azd Provision` \+ `azd deploy`** - 拆分时挂钩无法正确运行 * **不支持 Windows** — 打包挂钩是 `.sh` 脚本；使用 macOS、Linux 或 WSL * **Python 工具无法在本地运行** — 它们仅在部署后在云运行时中执行 * **Python 版本** — Azure Functions 运行时使用 Python 3.11；确保工具兼容 * **部署后模型更改**：运行 `azd env set MODEL_SELECTION "github:gpt-5.2"` 然后运行 `azd up`

功能 Markdown 代理

包含技能