azure-hosted-copilot-sdk：在 Azure 上构建和部署 Copilot 应用的得力工具
azure-hosted-copilot-sdk：在 Azure 上构建和部署 Copilot 应用的得力工具


如果你正在用 GitHub Copilot SDK 开发 AI 应用，又想把它们部署到 Azure 上，那么 azure-hosted-copilot-sdk 这个技能是你绕不开的帮手。它是 Microsoft Azure Skills 套件中的一员，专门解决 Copilot SDK 应用从开发到上线的全流程问题。截至 2026 年中，这个技能在 GitHub 上的安装量已接近 40 万次。

这个技能能做什么

azure-hosted-copilot-sdk 的核心价值在于：让你在 AI 编码助手中直接完成 Copilot SDK 应用的创建、配置、修改和部署，不需要来回切换工具或翻阅大量文档。

具体来说，它覆盖了以下几个关键环节。

项目脚手架搭建：通过 azd init --template azure-samples/copilot-sdk-service 一条命令，就能生成一个完整可用的 Copilot SDK 服务模板。模板采用 Express/TypeScript 作为 API 层，React/Vite 作为 Web UI，部署时以两个独立的容器应用形式运行。

CopilotClient 配置与会话管理：技能会指导你完成 CopilotClient 的实例化配置，以及 createSession 和 sendAndWait 这两个核心工作流的实现。聊天端点通过 Server-Sent Events（SSE）以 assistant.message_delta 事件流式返回 token 级别的增量响应。

BYOM（Bring Your Own Model）集成：如果你不想用 GitHub 的默认模型，而是想用自己的 Azure OpenAI 部署，这个技能也提供了完整的配置路径。Azure BYOM 模式下，每个请求都会获取一个全新的 bearer token，不存在 token 过期的问题。

部署到 Azure 容器应用或应用服务：技能涵盖了将应用部署到 Azure Container Apps 和 App Service 的完整流程，并与 azure-prepare 技能集成，完成环境准备。

三种模型路径：Copilot SDK 支持三种模型配置方式——GitHub 默认模型、GitHub 指定模型，以及 Azure BYOM。不同路径对应不同的认证方式：前两者使用 GITHUB_TOKEN，Azure BYOM 在本地开发时用 DefaultAzureCredential，生产环境用 ManagedIdentityCredential。

自动激活机制：当 AI 编码助手检测到你的项目 package.json 中包含 @github/copilot-sdk 依赖或代码中出现了 CopilotClient 时，这个技能会自动启用。你不需要手动调用它——助手会识别 SDK 上下文并自动应用技能指引。

安装方法

azure-hosted-copilot-sdk 是 Microsoft Azure Skills 套件的一部分，可以通过多种方式安装。

通过 npx 安装（推荐） ：

在项目根目录打开终端，执行以下命令：

bash
npx skills add https://github.com/microsoft/azure-skills --skill azure-hosted-copilot-sdk

另一种方式是通过 Azure Skills 仓库安装：

bash
npx skills add microsoft/azure-skills --skill azure-hosted-copilot-sdk

在 Copilot CLI 中安装：

如果你使用的是 Copilot CLI，需要先将 marketplace 添加进来，再安装插件：

text
/plugin marketplace add microsoft/azure-skills
/plugin install azure@azure-skills

在 Claude Code、Cursor 或 OpenClaw 中使用：

这个技能同样兼容 Claude Code、Cursor 和 OpenClaw 等 AI 编码助手。安装方式与上述 npx 命令一致。

前提条件：

在安装和使用之前，确保你已经具备以下条件：

  • 一个有效的 Azure 订阅（如果没有，可以先创建免费账号）

  • 已安装 Azure CLI（v2.60.0 或更高版本）并完成 az login 登录

  • 一个支持 Azure Skills 的 AI 编码助手，如 GitHub Copilot for Azure、安装了 Azure MCP 扩展的 VS Code，或 Claude Code

什么时候该用它

这个技能有明确的使用边界。知道什么时候该用、什么时候不该用，能帮你少走弯路。

应该使用的情况：

  • 要在 Azure 基础设施上构建自定义的 Copilot 应用

  • 使用 GitHub Copilot SDK 搭建 Copilot 驱动的应用

  • 将现有的 Copilot 应用部署到 Azure

  • 在 Azure 上托管应用，并使用 Azure OpenAI 模型或自带的模型（BYOM）

  • 将自己的大语言模型与 Copilot SDK 集成

  • 配置 Azure OpenAI 模型、托管身份认证和 Copilot SDK 服务

  • 使用 Copilot SDK 服务模板和 CopilotClient 库构建聊天应用

  • 实现会话管理和基于 GitHub Models API 的消息处理

不应该使用的情况：

  • 普通的 Azure 应用部署（不涉及 Copilot SDK）——这种情况应该用 azure-prepare + azure-deploy

  • GitHub Actions 或 CI/CD 流水线配置——有专门的工作流技能可用

  • 不涉及 Copilot SDK 集成的 Azure OpenAI 配置

使用案例

案例一：从零搭建一个 Copilot 聊天应用

假设你是一个开发者，想从头创建一个由 Copilot SDK 驱动的聊天应用并部署到 Azure。你只需要在 AI 助手中输入提示词，比如“Build a copilot-powered app”或“Run azd init copilot”。技能会自动激活，指导你完成从项目初始化、CopilotClient 配置到部署的全过程。

案例二：为现有项目添加 Copilot SDK 功能

如果你有一个现有的应用（不管是 Node.js、Python、Go 还是 .NET），想在里面加入 Copilot SDK 的 AI 功能，这个技能同样适用。它会先扫描项目中的指标文件来识别项目类型——package.json 对应 Node.js，requirements.txt 或 pyproject.toml 对应 Python，go.mod 对应 Go，*.csproj 或 *.sln 对应 .NET。然后指导你完成依赖添加、Copilot 端点创建、认证配置，最后将新路由注册到现有的服务实例中。

案例三：为 Copilot 应用添加新功能

当你已经有一个运行中的 Copilot SDK 应用，想给它添加一个新功能时，可以直接告诉 AI 助手“Add a feature to my copilot app”。技能会识别出这是一个已有的 SDK 项目，并提供针对性的修改指导。

案例四：切换到自己的 Azure OpenAI 模型

如果你不想用 GitHub 的默认模型，而是想用自己的 Azure OpenAI 部署，可以告诉助手“Bring your own model with Azure OpenAI”或“Modify my copilot app to use BYOM”。技能会指导你完成 @azure/identity 依赖的添加、token 获取逻辑的实现，以及 provider 配置中 bearerToken 和 model 参数的设置。

案例五：部署现有 SDK 应用到 Azure

如果你已经有一个 Copilot SDK 应用，只是想把它部署到 Azure 上，技能也提供了专门的路径。它会帮你添加必要的基础设施配置（Dockerfile、Bicep、azure.yaml），然后完成部署。

几个值得注意的细节

模板定制：官方模板提供了一个可运行的基础版本，但其中的路由、系统消息、工具定义和 UI 都可以按需修改。唯一需要注意的是，不要重新生成 Dockerfile、Bicep 和 azure.yaml 这几个基础设施文件。

超时配置：如果应用使用了多工具 AI 会话，需要在 nginx.conf.template 中将 proxy_read_timeout 从默认的 60 秒增加到 300 秒，否则会出现 504 超时错误。

模型名称必填：使用 BYOM 模式时，model 参数是必填的——SDK 会在缺少该参数时抛出异常。

加密内容限制：Copilot SDK 会对提示词内容进行加密，只有支持解密加密内容的模型才能与 BYOM 配合使用。