GitHub Copilot SDK 多平台集成指南架构、认证、安装与实战【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdkGitHub Copilot SDK 是 GitHub 官方提供的多语言开发套件将 Copilot CLI 背后的生产级 Agent 运行时封装为可编程调用的 API支持 Python、TypeScript、Go、.NET、Java 与 Rust 六种语言。本文以仓库根目录 README.md 为主线结合 docs/getting-started.md 教程、docs/auth/README.md 认证文档与各语言 SDK 的 README系统讲解 SDK 的定位、安装方式、JSON-RPC 架构、认证策略、权限模型与进阶能力帮助你判断如何在应用中嵌入 Copilot 的规划、工具调用与文件编辑等 Agent 能力。一、SDK 是什么无需自建编排的 Agent 运行时仓库根 README.md 的定位非常清晰GitHub Copilot SDK 暴露的是 Copilot CLI 背后的同一套引擎——一个经过生产验证的 Agent 运行时可以编程方式调用。使用它的核心价值在于你定义 Agent 行为工具、权限、提示词Copilot 负责规划planning、工具调用tool invocation、文件编辑等编排细节无需自行实现复杂的 Agent 循环。Your Application ↓ SDK Client ↓ JSON-RPC Copilot CLI (server mode)从 docs/features/README.md 可以看到SDK 之上还叠加了 hooks、自定义 agents、MCP 服务器、skills、插件目录、会话持久化、远程会话等丰富特性是一个面向生产环境的完整 SDK 栈。二、支持的平台与安装方式根 README 提供了完整的 SDK 矩阵下表继承自 README.mdSDK仓库位置安装命令Node.js / TypeScriptnodejs/npm install github/copilot-sdkPythonpython/pip install github-copilot-sdkGogo/go get github.com/github/copilot-sdk/go.NETdotnet/dotnet add package GitHub.Copilot.SDKRustrust/cargo add github-copilot-sdkJavajava/Maven 坐标com.github:copilot-sdk-java安装细节见 java/README.md 的 Maven/Gradle 章节各 SDK 均有独立的语言版本下限要求详见对应 README 的 Prerequisites 小节nodejs/README.md、python/README.md、go/README.md、rust/README.md、java/README.md、dotnet/README.md。例如 Node.js SDK 要求Node.js ^20.19.0 或 22.12.0Python SDK 要求Python 3.11Go SDK 要求Go 1.24。文档特别提示语言运行时版本过低可能导致包管理器静默解析到过时的 SDK 版本而非报错务必先核对版本下限。三、架构核心JSON-RPC 与运行时生命周期所有 SDK 都通过 JSON-RPC 与 Copilot CLI 服务器通信。SDK 会自动管理 CLI 进程的生命周期——启动、连接、停止都不需要你干预。3.1 三种运行形态结合 docs/setup/bundled-cli.md 与 nodejs/README.md 的RuntimeConnection文档SDK 的运行时接入方式可分为三类stdio默认SDK 以子进程方式拉起 Copilot 运行时通过 stdin/stdout 通信。Node.js、Python、.NET 的 CLI 以依赖形式自动捆绑bundled CLI无需单独安装TCPRuntimeConnection.forTcpSDK 把运行时以 TCP 服务器方式拉起便于跨进程共享外部连接RuntimeConnection.forUri/ Go 的URIConnection/ Rust 的Transport::External连接到一个已经运行在 server mode 的 CLI 服务器SDK 不再负责进程生命周期进程内FFI实验性RuntimeConnection.forInProcess()通过原生 C ABI 将运行时宿主在当前应用进程内。3.2 捆绑 CLI 与手动安装README.md 与 docs/setup/bundled-cli.md 明确Node.js / Python / .NETCLI 自动捆绑Python 安装后建议执行python -m copilot download-runtime一次性下载运行时跳过时首次使用会自动下载Go / Java / Rust默认不捆绑需手动安装 CLI 或确保copilot在 PATH 中Go 与 Rust 额外提供了应用级 CLI 捆绑bundling能力Go 可在构建期通过 go/cmd/bundler 工具把 CLI 嵌入二进制Java 可通过setCliPath(...)指定二进制位置或用setCliUrl(...)连接运行中的服务器高级用法可通过COPILOT_CLI_PATH环境变量或连接配置覆盖 CLI 二进制。Python SDK 还支持COPILOT_CLI_EXTRACT_DIR、COPILOT_SKIP_CLI_DOWNLOAD等环境变量见 python/README.md。3.3 连接外部 CLI 服务器当需要调试保持 CLI 常驻查看日志、多客户端共享资源或自定义运行环境时可让 CLI 以 server mode 独立运行# 监听随机端口 copilot --headless # 指定端口默认仅接受 127.0.0.1 回环连接 copilot --headless --port 4321 # 监听所有网卡用于容器或远程部署需自行配合防火墙/私网/反向代理等网络控制 copilot --headless --host 0.0.0.0 --port 4321SDK 侧通过 URL 配置连接例如 TypeScriptimport { CopilotClient, approveAll } from github/copilot-sdk; const client new CopilotClient({ cliUrl: localhost:4321 }); const session await client.createSession({ onPermissionRequest: approveAll });Go 使用copilot.NewClient(copilot.ClientOptions{Connection: copilot.URIConnection{URL: localhost:4321}})Rust 使用Transport::External { host, port, connection_token }。一旦指定外部连接SDK 将不再 spawn 或管理 CLI 进程。四、快速开始约 5 行代码发送第一条消息docs/getting-started.md 提供了完整的端到端教程从创建客户端到流式响应、自定义工具、交互式助手这里给出最精简的核心模式。前置条件是已安装并认证 Copilot CLINode.js/Python/.NET 自动捆绑可用copilot --version验证。TypeScript创建index.tsimport { 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);运行npx tsx index.ts先npm install github/copilot-sdk tsx。Python创建main.pyimport 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())运行python main.py。Go创建main.gopackage main import ( context fmt log os copilot github.com/github/copilot-sdk/go ) func main() { ctx : context.Background() client : copilot.NewClient(nil) if err : client.Start(ctx); err ! nil { log.Fatal(err) } defer client.Stop() session, err : client.CreateSession(ctx, copilot.SessionConfig{Model: auto}) if err ! nil { log.Fatal(err) } response, err : session.SendAndWait(ctx, copilot.MessageOptions{Prompt: What is 2 2?}) if err ! nil { log.Fatal(err) } if d, ok : response.Data.(*copilot.AssistantMessageData); ok { fmt.Println(d.Content) } os.Exit(0) }Rust使用github_copilot_sdk::Client::start与SessionConfig::default().with_permission_handler(Arc::new(ApproveAllHandler)).NET使用new CopilotClient()与PermissionHandler.ApproveAllJava使用new CopilotClient()、new SessionConfig().setModel(auto).setOnPermissionRequest(PermissionHandler.APPROVE_ALL)。各语言完整可运行代码均在 docs/getting-started.md 中。运行后应输出4——恭喜第一个 Copilot 应用完成。4.1 会话生命周期 APISDK 客户端提供了一组基础方法以 TypeScript 为例其余语言语义一致方法说明start()/stop()/forceStop()启动 / 优雅停止 / 强制停止 CLI 服务器createSession(config)创建会话可指定sessionId、model、tools、streaming等resumeSession(sessionId)恢复历史会话会话状态持久化于~/.copilot/session-state/{sessionId}/ping()连通性检查listSessions()/deleteSession(id)会话列表与删除onLifecycle(...)订阅session.created/session.foreground等生命周期事件Python 与 .NET 还支持异步上下文管理器async with CopilotClient() as client/await using自动释放资源。五、流式响应与事件订阅docs/getting-started.md 的 Step 3 展示了如何把等完整响应升级为逐字输出。在createSession时开启streaming: true然后订阅事件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(); // New line when done }); await session.sendAndWait({ prompt: Tell me a short joke });关键事件类型完整清单见 nodejs/README.md 的 Event Types 章节与 docs/features/streaming-events.mdassistant.message_delta—— 流式增量文本deltaContentassistant.reasoning_delta—— 推理过程的流式增量依赖模型是否支持assistant.message/assistant.reasoning—— 最终完整消息无论是否开启流式都会发送session.idle—— 会话处理完毕可作为完成信号tool.execution_start/tool.execution_complete—— 工具执行生命周期。各语言的订阅方式略有差异TypeScript 的session.on(eventType, handler)支持按事件类型订阅并返回退订函数Go 在回调中做switch类型断言Rust 用session.subscribe()返回 channel 后按event.event_type过滤.NET 用模式匹配pattern matchingJava 用session.on(AssistantMessageDeltaEvent.class, ...)。六、自定义工具让 Copilot 调用你的代码docs/getting-started.md 的 Step 4 给出了工具定义的三要素description做什么、parameters参数 schema、handler执行的代码。以天气查询工具为例TypeScriptimport { 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 }) { const { city } args; // In a real app, youd call a weather API here return { city, temperature: 62°F, condition: cloudy }; }, }); const client new CopilotClient(); const session await client.createSession({ model: auto, streaming: true, tools: [getWeather], });调用流程继承自文档的 How tools work 一节Copilot 根据用户问题决定调用工具 → 发送带参数的工具调用请求 → SDK 执行你的 handler → 结果回传 Copilot → Copilot 把结果整合进回复。Python 用define_tool装饰器配合 Pydantic 参数模型Go 用copilot.DefineTool(name, desc, func)配合 struct tagRust 用define_tool serdeDeserializeJsonSchemaderive.NET 用CopilotTool.DefineToolMicrosoft.Extensions.AI的AIFunctionFactoryOptionsJava 用ToolDefinition.create(...)。6.1 工具的高级选项nodejs/README.md 补充了工具定义的进阶能力Zod schema 支持TypeScript 可用z.object({...})替代手写 JSON Schema获得类型安全覆盖内置工具注册与内置工具如edit_file、read_file同名的工具会抛错需显式设置overridesBuiltInTool: true跳过权限确认设置skipPermission: true让只读类工具免于权限提示延迟加载defer: auto默认允许工具通过工具搜索按需加载never强制预加载handler 返回值任意 JSON 可序列化值自动包装、字符串或ToolResultObject完全控制结果元数据。七、认证五种方式与优先级根 README 的 FAQ 列出了四种认证方式docs/auth/authenticate.md 将其扩充为完整矩阵方法适用场景是否需要 Copilot 订阅GitHub 已登录用户交互式应用CLI OAuth 设备流登录凭据存于系统钥匙串是GitHub OAuth App代表用户行事的 Web/SaaS 应用传用户访问令牌是环境变量CI/CD、自动化、server-to-server是Server-to-server组织级组织归属的自动化用 GitHub Actions 或 GitHub App 安装令牌无需用户订阅需组织策略BYOK自带密钥使用自有模型供应商 API 密钥否支持的令牌类型gho_OAuth 用户令牌、ghu_GitHub App 用户令牌、github_pat_细粒度 PAT不支持已废弃的ghp_经典 PAT。环境变量优先级COPILOT_GITHUB_TOKEN推荐→GH_TOKEN→GITHUB_TOKEN。多凭据并存时的认证优先级见 docs/auth/authenticate.md显式传入的gitHubToken客户端或会话配置直接 API 令牌GITHUB_COPILOT_API_TOKENCOPILOT_API_URL环境变量令牌COPILOT_GITHUB_TOKEN→GH_TOKEN→GITHUB_TOKEN存储的 OAuth 凭据来自copilotCLI 登录GitHub CLIgh auth凭据。多用户服务端部署时应为每个会话传递独立的gitHubToken保证会话以正确的 GitHub 身份运行详见 docs/setup/multi-tenancy.md。若想禁止 SDK 自动使用存储凭据可设置useLoggedInUser: false。7.1 会话级滚动令牌多用户服务对于多用户服务与集成场景docs/auth/authenticate.md 推荐使用gitHubTokenProvider在会话上注册令牌提供器运行时按需回调initial/refresh令牌必须带正数expiresIn剩余秒数生产令牌通常为 8 小时即8 * 60 * 60const session await client.createSession({ gitHubTokenProvider: async ({ host }) ({ kind: token, accessToken: await acquireTokenForHost(host), expiresIn: 8 * 60 * 60, }), });初次获取发生在会话创建/恢复时失败会拒绝创建操作而不是回退到环境认证空闲会话只会在下一次消耗凭据的操作前刷新没有后台定时器。八、BYOK无需 GitHub 订阅的自带密钥模式根 README 明确BYOK 是唯一不需要 GitHub Copilot 订阅的使用方式通过配置自有 LLM 供应商OpenAI、Microsoft Foundry、Anthropic 等的 API 密钥访问模型。注意 BYOK 仅支持基于密钥的认证不支持 Microsoft Entra IDAzure AD、托管身份与第三方身份提供商。TypeScript 的 BYOK 配置示例docs/auth/byok.md 有完整说明const session await client.createSession({ model: gpt-5.4, // 使用自定义 provider 时必须显式指定 model provider: { type: openai, baseUrl: https://api.openai.com/v1, apiKey: process.env.OPENAI_API_KEY, }, });Provider 配置要点nodejs/README.md 的 Custom Providers 章节typeopenai默认、azure或anthropicAzure OpenAI 端点*.openai.azure.com必须用azure类型baseUrlAzure 只需填主机名不要带/openai/v1路径SDK 自动拼接apiKey可选本地 provider 如 Ollama 可省略bearerToken优先于apiKeywireApiOpenAI/Azure 的 API 格式completions或responsesazure.apiVersionAzure API 版本省略时运行时使用 GA 版无版本v1路由自定义 provider 时model参数必填否则 SDK 抛错。九、默认工具与权限处理根 README 的 FAQ 说明默认情况下 SDK 暴露 Copilot CLI 的第一方工具类似 CLI 的--allow-all模式但工具执行仍受各 SDK 权限处理器permission handler约束应用可以批准、拒绝或自定义工具调用。权限处理器在每次工具执行前被调用nodejs/README.md 的 Permission Handling 章节const session await client.createSession({ onPermissionRequest: (request, invocation) { if (request.kind shell) { return { kind: reject, feedback: Shell commands are not allowed. }; } return { kind: approve-once }; }, });返回的决策类型PermissionDecision包括Kind含义approve-once仅允许这一次请求approve-for-session允许并在本会话内记住该批准approve-for-location允许并在项目位置git root 或 cwd持久化reject拒绝可附带反馈信息告诉模型原因{ kind: no-result }不决策请求保持 pending 等待外部解决未提供处理器时权限请求会作为事件发出并保持 pending。request.kind可区分操作类型shell、write、read、mcp、custom-tool、url、memory、hook等。内置的approveAll助手在 managed settings 禁用时可用启用enableManagedSettings时会抛错应改用自定义处理器。十、自定义 Agents、Skills 与 MCP 扩展根 README FAQ 确认 SDK 允许定义自定义 agents、skills 和 tools。docs/features/README.md 列出了完整能力地图。快速示例TypeScriptMCP 服务器连接 GitHub 官方 MCP 获取仓库、Issue、PR 能力const session await client.createSession({ mcpServers: { github: { type: http, url: https://api.githubcopilot.com/mcp/, }, }, });自定义 Agentconst session await client.createSession({ customAgents: [{ name: pr-reviewer, displayName: PR Reviewer, description: Reviews pull requests for best practices, prompt: You are an expert code reviewer. Focus on security, performance, and maintainability., }], });系统消息定制systemMessage支持三种模式——默认追加保留 CLI 人格与 SDK 注入的安全护栏、mode: customize针对tone、code_change_rules、guidelines等 12 个命名分段执行replace/remove/append/prepend/preserve五种操作、mode: replace完全替换、移除所有护栏。分段 ID 完整列表见 docs/getting-started.md 与 nodejs/README.md。十一、计费、订阅与常见问题根 README 的 FAQ 给出了明确的计费口径订阅要求标准用法需要 GitHub Copilot 订阅包含带有限额的免费层BYOK 除外计费模型与 Copilot CLI 相同每个 prompt 计入用量额度模型支持Copilot CLI 可用的全部模型 SDK 均支持且 SDK 暴露了运行时获取可用模型的方法listModels()生产就绪SDK 已 GAgenerally available遵循语义化版本发布记录见 CHANGELOG.md问题反馈通过 GitHub Issues 报告 bug 或请求特性。十二、观测性与遥测SDK 内置 OpenTelemetry 支持docs/observability/opentelemetry.md传入telemetry配置即启用无需额外开关const client new CopilotClient({ telemetry: { otlpEndpoint: http://localhost:4318, // OTLP HTTP 端点 }, });TelemetryConfig支持六项配置otlpEndpointOTLP HTTP 端点 URL、otlpProtocolhttp/json或http/protobuf、filePathJSON-lines 追踪文件输出、exporterTypeotlp-http或file、sourceName埋点作用域名、captureContent是否捕获消息内容。SDK 与 CLI 之间的 W3C Trace Context 自动传播SDK → CLI 在session.create、session.resume、session.sendRPC 调用中注入traceparent/tracestate头CLI → SDK 在调用工具 handler 时把 CLI 侧 span 上下文传给工具代码。各语言依赖不同Python 需pip install github-copilot-sdk[telemetry]Node 需可选 peer 依赖opentelemetry/api.NET 用内置System.Diagnostics.ActivityRust 无需额外依赖。十三、延伸阅读docs/README.md —— 完整文档索引docs/getting-started.md —— 零基础到流式响应 自定义工具的完整教程docs/setup/README.md —— 架构、部署模式与水平扩展docs/auth/README.md —— 认证总览GitHub OAuth、BYOK、server-to-serverdocs/auth/byok.md —— BYOK 完整配置说明docs/features/README.md —— hooks、自定义 agents、MCP、skills 等功能地图docs/observability/opentelemetry.md —— TelemetryConfig 与追踪上下文传播docs/troubleshooting/debugging.md —— 常见问题排查各语言参考nodejs/README.md、python/README.md、go/README.md、rust/README.md、dotnet/README.md、java/README.mdCHANGELOG.md —— 版本发布记录结语从根 README.md 出发可以看到GitHub Copilot SDK 的定位是给每个应用接入 AgentSDK 层屏蔽了 JSON-RPC 协议与 CLI 进程管理应用只需聚焦于工具定义、权限策略与提示词设计。安装一个 SDK 包、创建会话、发送消息、注册自定义工具即可把 Copilot 的规划与工具调用能力嵌入到桌面应用、CLI 工具、Web 服务乃至多租户后端中配合 BYOK、滚动令牌、MCP 与 hooks它可以覆盖从原型到生产环境的完整集成路径。【免费下载链接】copilot-sdkMulti-platform SDK for integrating GitHub Copilot Agent into apps and services项目地址: https://gitcode.com/GitHub_Trending/co/copilot-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考