GitHub Copilot SDK 文档全景指南从首个 Agent 应用到生产级部署【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk本指南以 Copilot SDK 的官方文档索引docs/README.md为骨架为读者梳理这条完整的成长路径先通过 Getting Started 用五分钟构建第一个 Copilot 应用再按生产场景选择部署与认证方案随后在 Features 与 Hooks 参考中掌握流式事件、自定义工具、MCP、Skills、会话钩子等核心能力最后借助故障排查、可观测性与集成指南将应用打磨到可上线状态。读完本文你将掌握如何在 Node.js/TypeScript、Python、Go、.NET、Java、Rust 六种语言中定位并使用 SDK 的全部能力同时理解其底层 JSON-RPC 架构与源码实现。文档地图30 秒找到你需要的指南docs/README.md是官方文档的总入口它把全部资料按目标场景组织成一张导航表。无论你处于哪个阶段都可以直接定位我的目标去向构建第一个应用Getting Started——端到端教程覆盖流式响应与自定义工具生产环境部署Setup Guides——架构、部署模式、横向扩展配置认证Authentication——GitHub OAuth、服务端到服务端认证、环境变量、BYOK为应用添加能力Features——hooks、自定义 Agent、MCP、skills 等排查问题Troubleshooting——常见问题与解决方案在目录结构上仓库将文档分为八个一级模块docs/getting-started.md入门教程、docs/setup/部署配置、docs/auth/认证、docs/features/功能指南、docs/hooks/钩子 API 参考、docs/troubleshooting/故障排查、docs/observability/可观测性与docs/integrations/第三方集成。下面逐一展开。从零开始Getting Started 教程入门教程是官方推荐的起点。教程带你构建一个命令行天气助手用户可以询问西雅图天气怎么样Copilot 调用你自定义的get_weather工具返回结果。完成教程后你会掌握三条核心能力发送消息、流式接收响应、让 Copilot 调用你的代码。环境准备Copilot CLINode.js、Python、.NET SDK 会随包自动携带 CLI见 Bundled CLIGo、Java、Rust 需要手动安装 CLI 或使用各自的应用级 CLI 打包能力。语言运行时各 SDK 在自身 README 的 Prerequisites 小节声明最低版本要求——Node.jsNode.js ^20.19.0 或 22.12.0、PythonPython 3.11、Go、Rust、Java、.NET。安装后验证 CLI 可用copilot --version安装 SDK六种语言# Node.js / TypeScript npm install github/copilot-sdk tsx # Python pip install github-copilot-sdk # Go go get github.com/github/copilot-sdk/go # Rust示例还需 tokio、serde、schemars cargo add github-copilot-sdk --features derive # .NET dotnet add package GitHub.Copilot.SDK # JavaMaven # dependency # groupIdcom.github/groupId # artifactIdcopilot-sdk-java/artifactId # version${copilot.sdk.version}/version # /dependency第一条消息约 5 行代码以 Node.js/TypeScript 为例createSession({ model: auto })创建会话sendAndWait同步等待完整回复import { CopilotClient } from github/copilot-sdk; const client new CopilotClient(); const session await client.createSession({ model: auto }); const response await session.sendAndWait({ prompt: What is 2 2? }); console.log(response?.data.content); await client.stop(); process.exit(0);Python 版本在此基础上需要显式传入权限处理器PermissionHandler.approve_all因为工具执行始终受各 SDK 权限处理器约束import asyncio from copilot import CopilotClient from copilot.session import PermissionHandler async def main(): client CopilotClient() await client.start() session await client.create_session(on_permission_requestPermissionHandler.approve_all, modelauto) response await session.send_and_wait(What is 2 2?) print(response.data.content) await client.stop() asyncio.run(main())Go、Rust、.NET、Java 的等价代码均收录在入门教程中Go 通过copilot.NewClient(nil)client.Start(ctx)启动Rust 使用Client::start(ClientOptions::default())与ApproveAllHandler.NET 使用await using var client new CopilotClient()Java 通过new CopilotClient()与PermissionHandler.APPROVE_ALL完成同样的调用链。六种语言运行后都应输出4。流式响应让回复逐字出现将streaming: true传入会话配置并订阅会话事件即可实时渲染回复。Node.js/TypeScript 写法const session await client.createSession({ model: auto, streaming: true }); session.on(assistant.message_delta, (event) { process.stdout.write(event.data.deltaContent); }); session.on(session.idle, () console.log());SDK 提供三种事件订阅方法on(handler)订阅全部事件返回取消订阅函数、on(eventType, handler)订阅指定类型Node.js/TypeScript 专属、Rust 的subscribe()返回事件流后按event_type过滤。各语言的事件过滤方式各异Go 用类型断言switch d : event.Data.(type).NET 用switch (ev)模式匹配Java 用session.on(AssistantMessageDeltaEvent.class, ...)按类型注册。自定义工具让 Copilot 调用你的代码定义工具是 SDK 最具价值的能力之一。以天气工具为例Node.js/TypeScript 使用defineTool声明名称、描述、JSON Schema 参数与处理器import { CopilotClient, defineTool } from github/copilot-sdk; const getWeather defineTool(get_weather, { description: Get the current weather for a city, parameters: { type: object, properties: { city: { type: string, description: The city name } }, required: [city], }, handler: async (args: { city: string }) { // 真实应用中在此调用天气 API return { city: args.city, temperature: 62°F, condition: sunny }; }, }); const session await client.createSession({ model: auto, streaming: true, tools: [getWeather] });其他语言的定义方式体现了各自的类型系统Python 用define_tool(description...)装饰器配合 Pydantic 参数模型Go 用copilot.DefineTool(get_weather, description, func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error))并以结构体标签jsonschema:The city name描述参数Rust 用define_tool配合#[derive(Deserialize, JsonSchema)].NET 用CopilotTool.DefineTool包装Microsoft.Extensions.AI的AIFunctionFactoryOptionsJava 用ToolDefinition.create(name, description, Map, invocation - ...)。组装成交互式助手教程最后把以上能力组装为可交互的 REPL 式助手循环读取用户输入 →sendAndWait发送 → 流式打印回复输入exit退出。完整的 Node.js/TypeScript 与 Python 实现在教程中均可直接运行仓库中 nodejs/samples/chat.ts、python/samples/chat.py、go/samples/chat.go、dotnet/samples/Chat.cs、rust/examples/chat.rs 还提供了更完整的独立可运行示例。Setup按部署形态选择接入方式Setup 指南覆盖从本地开发到大规模生产部署的完整形态首篇 choosing-a-setup-path 提供架构、角色画像与决策矩阵帮助你先选路再动手默认方案Bundled CLISDK 自动包含 CLI无需单独安装——这是 Node.js、Python、.NET 的默认形态见 bundled-cli.md。从 Python README 可以看到具体机制安装后会通过python -m copilot download-runtime下载平台发布包并用官方SHA256SUMS.txt校验后直接落地copilot-runtime与相邻的runtime.node缓存路径按平台分别位于~/.cache/github-copilot-sdk/cli/version/prebuilds/Linux、~/Library/Caches/...macOS、%LOCALAPPDATA%\...Windows若跳过下载SDK 会在首次托管 stdio/TCP 使用时自动执行同样的 staging。本地 CLI使用你自己的 CLI 二进制或已运行的实例适合已有 CLI 环境的场景见 local-cli.md。Node.js SDK 支持通过COPILOT_CLI_PATH环境变量或连接配置的path覆盖内置运行时。后端服务以无头headlessCLI 通过 TCP 提供服务端部署见 backend-services.md。进程内运行时实验性把运行时以原生 C ABIFFI方式宿主在你的应用进程内见 in-process-runtime.md。需注意因为运行时共享进程env、telemetry、workingDirectory在该传输方式下会被拒绝应设置在主进程上Python 需通过python -m copilot download-runtime --in-process预先准备 FFI 所需的原生库。GitHub OAuth实现完整 OAuth 登录流程见 github-oauth.md。Azure Managed Identity配合 Microsoft Foundry 走 BYOK 路线见 azure-managed-identity.md。横向扩展与多租户水平扩展、隔离模式见 scaling.md多用户服务端部署的mode: empty、会话隔离、integration ID、sessionFs 等选项见 multi-tenancy.md。Node.js SDK 中mode?: empty | copilot-cli即为默认策略开关多用户服务端模式应使用empty。Node.js SDK 的连接方式由RuntimeConnection工厂函数抽象forStdio()默认spawn 运行时走 stdin/stdout、forTcp({ port, connectionToken, ... })spawn 为 TCP 服务器、forUri(url, { connectionToken })连接已运行的实例与gitHubToken/useLoggedInUser互斥、forInProcess()实验性 FFI。Authentication认证方式与优先级认证文档要求按部署场景选择认证方式并明确给出了认证优先级同时配置多份凭据时显式 SDK token 优先其次是直接 Copilot API 环境认证、环境变量 GitHub token、已存储的 Copilot CLI 凭据最后才是 GitHub CLI 凭据服务端到服务端安装 token 走环境变量路径。认证总览方法清单、优先级顺序与示例见 authenticate.md。服务端到服务端认证使用 GitHub Actions 或 GitHub App 安装 token 实现组织归属的自动化任务见 server-to-server-tokens.md。BYOKBring Your Own Key配置 OpenAI、Azure、Anthropic 等自有 API 密钥无需 GitHub 认证即可使用 SDK见 byok.md。注意 BYOK 仅支持密钥认证不支持 Microsoft Entra IDAzure AD、托管身份与第三方身份提供者。多用户服务端模式下需要为每个会话传入gitHubToken确保每个会话以正确的 GitHub 身份运行见 multi-tenancy.md。项目根 README 汇总了全部认证途径已登录 GitHub 用户复用copilotCLI 登录的 OAuth 凭据、OAuth GitHub App透传用户 token、环境变量COPILOT_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN与 BYOK。FeaturesSDK 功能全景功能指南是 SDK 能力最集中的模块每个功能都有对应实战文档语言示例覆盖 TypeScript、Python、Go、.NET、Java、Rust功能说明The Agent LoopCLI 如何处理一条 prompt——工具调用循环、回合与完成信号Hooks拦截并定制会话行为——控制工具执行、转换结果、处理错误Custom Agents定义带作用域工具与指令的专用子 AgentFleet Mode为大型独立工作流并行派发多个子 AgentMCP Servers集成 Model Context Protocol 服务器以获取外部工具Skills从目录加载可复用提示模块Plugin Directories把 skills、hooks、MCP 服务器、agents 打包为单个可加载插件Session limits为会话设置 AI Credits 预算并观察预算事件Citations把助手回复链接回其支持来源Image Input以附件形式向会话发送图片Streaming Events订阅 40 种实时会话事件Usage and Billing读取 token 数、上下文窗口利用率、AI credit 成本与账户配额Client info声明应用与集成身份用于运行时遥测归因Steering Queueing控制消息投递——即时 steering 与顺序 queueingContext Clearing用终端工具安全地替换对话上下文Session Persistence跨重启恢复会话、管理会话存储Remote Sessions通过 Mission Control 把本地托管会话共享到 GitHub Web 与移动端Cloud Sessions通过 Mission Control 在 GitHub 托管计算上运行会话从源码结构可以印证这些能力的落点Python SDK 的 tools.py 承载工具定义、session_events.py 定义事件类型、client.py 实现客户端与会话生命周期Node.js 对应 src/toolSet.ts、src/session.ts、src/client.ts。MCP 工具的运行时名称为server-key-tool-name形式在availableTools/excludedTools中建议用new ToolSet().addMcp(server-key-tool-name)或原生mcp:server-key-tool-name形式Node.js README。Hooks Reference会话钩子 API 参考Hooks 参考提供每个会话钩子的详细 API 文档用于在会话关键节点注入自定义逻辑Hooks overview快速上手、常见模式与钩子调用上下文Pre-tool use批准、拒绝或修改工具调用Post-tool use转换工具结果User prompt submitted修改或过滤用户消息User prompt transformed检查或替换模型面提示词Session lifecycle会话开始与结束Error handling自定义错误处理这与权限处理器的职责相呼应SDK 默认暴露 Copilot CLI 的第一方工具类似 CLI 的--allow-all但工具执行仍受各 SDK 权限处理器约束应用可以批准、拒绝或定制工具调用见根 README 的 FAQ。仓库测试对该机制有大量覆盖例如 Python test_hooks_e2e.py、Node.js e2e 测试目录、Go hooks_e2e_test.go 与 .NET HookLifecycleAndOutputE2ETests.cs。Troubleshooting故障排查排查指南包含三个入口调试指南常见问题与解决方案MCP 调试MCP 专属问题排查兼容性矩阵SDK 与 CLI 功能对照表Observability可观测性可观测性文档聚焦 OpenTelemetry 插桩SDK 内置TelemetryConfig与 trace context 传播详见 opentelemetry.md。Python 用户可通过pip install github-copilot-sdk[telemetry]启用遥测扩展。此外订阅assistant.usage事件并检查apiEndpointAssistantUsageApiEndpoint即可进行成本归因与端点级分析参考 streaming-events.md。仓库中对应实现包括 python/copilot/_telemetry.py、nodejs/src/telemetry.ts、go/telemetry.go、dotnet/src/Telemetry.cs。Integrations第三方平台集成集成指南目前收录 Microsoft Agent Framework介绍如何在 MAF 多 Agent 工作流中使用 SDK。源码级洞察JSON-RPC 架构与多语言实现理解 SDK 的底层架构有助于用好上述全部功能。项目根 README 明确了核心架构所有语言的 SDK 都通过 JSON-RPC 与 Copilot CLI 服务器通信Your Application ↓ SDK Client ↓ JSON-RPC Copilot CLI (server mode)SDK 自动管理 CLI 进程生命周期也可以连接外部 CLI 服务器详见 getting-started.md 的 server 模式说明。各语言的通信与协议层实现位置如下Pythonclient.py 客户端、_jsonrpc.py 协议层、rpc.py 与 session_events.py 生成的事件模型python/copilot/generated/下为代码生成产物Node.js / TypeScriptsrc/client.ts、src/ffiRuntimeHost.ts、src/generated/Goclient.go、copilot_request_handler.go、zrpc.go协议层.NETsrc/Client.cs、src/JsonRpc.cs、src/Generated/Rustsrc/lib.rs、src/jsonrpc.rs、src/rpc.rsJavasdk/src/约 1890 个 Java 文件含生成的协议类型这些协议层与事件类型大量由 scripts/codegen/ 下的生成器csharp.ts、go.ts、python.ts、rust.ts、typescript.ts统一产出保证六个 SDK 的行为一致这也是六种语言同一套事件语义的工程基础。FAQ高频问题速览根 README 对常见问题给出了明确回答可直接作为决策依据需要 Copilot 订阅吗需要除非使用 BYOK——配置自有 LLM 提供商 API 密钥后可脱离 GitHub 认证使用 SDK。计费方式与 Copilot CLI 一致每条 prompt 计入使用额度。需要单独安装 CLI 吗Node.js、Python、.NET 自动捆绑Go、Java、Rust 需手动安装或使用应用级 CLI 打包能力也可通过COPILOT_CLI_PATH覆盖二进制或连接外部服务器。默认启用哪些工具SDK 暴露 Copilot CLI 的第一方工具类似--allow-all工具执行仍受各 SDK 权限处理器约束可通过客户端选项启用/禁用特定工具。支持自定义 Agent、Skills、工具吗支持各语言 SDK 均可定义自定义 agent、skills 与 tools。支持哪些模型所有 Copilot CLI 可用模型均受支持SDK 还提供运行时查询可用模型的方法。生产可用吗SDK 已 GA一般可用并遵循语义化版本控制发布记录见 CHANGELOG.md。结语按需取用的完整文档体系这份文档地图的价值在于分层取用初学从 Getting Started 走完第一遍全流程做架构决策时对照 Setup 与 Auth为应用叠加能力时翻阅 Features深入调优时参考 Hooks 与 Observability遇到问题则回到 Troubleshooting。配合各语言目录下的 SDK READMEnodejs/README.md、python/README.md、go/README.md、dotnet/README.md、rust/README.md、java/README.md与 CHANGELOG.md即可覆盖从首个 Demo 到生产集群的完整生命周期。【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考