github-copilot-sdk

GitHub Copilot SDK - 综合技能

概述

GitHub Copilot SDK 让开发者能够以编程方式在应用程序中嵌入 Copilot 的智能体工作流。它将 Copilot CLI 背后的同一引擎作为经过生产环境验证的 Agent 运行时开放出来，你可以通过代码调用它。

何时使用 Copilot SDK

在以下情况下使用 Copilot SDK：

• 构建需要 Copilot AI 能力的应用程序
• 实现具备工具调用能力的自定义 AI 助手
• 创建利用 Copilot 代码理解能力的集成
• 连接到 MCP（Model Context Protocol）服务以使用标准化工具
• 需要在自定义 UI 中使用流式响应

以下情况不适用：

• GitHub Copilot CLI 已经足够（直接使用 CLI）
• 无需编程集成（在 VS Code 中使用 Copilot）
• 构建不使用工具的简单聊天应用（使用标准 LLM API）

语言支持

SDK	安装
Node.js/TypeScript	npm install @github/copilot-sdk
Python	pip install github-copilot-sdk
Go	go get github.com/github/copilot-sdk/go
.NET	dotnet add package GitHub.Copilot.SDK

先决条件

1. 已安装并完成身份验证的 GitHub Copilot CLI
2. 有效的 Copilot 订阅（提供有使用限制的免费层级）

快速入门

最简示例（TypeScript）

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({ model: "gpt-4.1" });

const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
console.log(response?.data.content);

await client.stop();

最简示例（Python）

import asyncio
from copilot import CopilotClient

async def main():
    client = CopilotClient()
    await client.start()
    session = await client.create_session({"model": "gpt-4.1"})
    response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
    print(response.data.content)
    await client.stop()

asyncio.run(main())

添加流式响应

const session = await client.createSession({
  model: "gpt-4.1",
  streaming: true,
});

session.on((event) => {
  if (event.type === "assistant.message_delta") {
    process.stdout.write(event.data.deltaContent);
  }
});

await session.sendAndWait({ prompt: "Tell me a joke" });

添加自定义工具

import { defineTool } from "@github/copilot-sdk";

const getWeather = defineTool("get_weather", {
  description: "Get weather for a city",
  parameters: {
    type: "object",
    properties: {
      city: { type: "string", description: "City name" },
    },
    required: ["city"],
  },
  handler: async ({ city }) => ({
    city,
    temperature: `${Math.floor(Math.random() * 30) + 50}°F`,
    condition: "sunny",
  }),
});

const session = await client.createSession({
  model: "gpt-4.1",
  tools: [getWeather],
});

核心概念

架构

Your Application → SDK Client → JSON-RPC → Copilot CLI (server mode)

SDK 会自动管理 CLI 进程生命周期，也可以连接到外部 CLI 服务。

关键组件

1. CopilotClient：入口点，用于管理与 Copilot CLI 的连接
2. Session：包含模型、工具和历史记录的对话上下文
3. 工具：Copilot 可调用的自定义函数
4. 事件：流式响应和工具调用通知
5. MCP 集成：连接到 Model Context Protocol 服务

会话配置

const session = await client.createSession({
  model: "gpt-4.1", // Model to use
  streaming: true, // Enable streaming
  tools: [myTool], // Custom tools
  mcpServers: {
    // MCP server connections
    github: {
      type: "http",
      url: "https://api.githubcopilot.com/mcp/",
    },
  },
  systemMessage: {
    // Custom system prompt
    content: "You are a helpful assistant.",
  },
  customAgents: [
    {
      // Custom agent personas
      name: "code-reviewer",
      displayName: "Code Reviewer",
      description: "Reviews code for best practices",
      prompt: "Focus on security and performance.",
    },
  ],
});

导航指南

何时阅读辅助文件

reference.md — 在以下情况下阅读：

• 需要查看全部 4 种语言的完整 API 参考
• 需要查看包含参数和返回类型的所有方法签名
• 需要了解会话配置选项
• 需要了解事件类型和处理方式
• 需要连接外部 CLI 服务

examples.md — 在以下情况下阅读：

• 需要获取适用于全部 4 种语言的可直接复制粘贴的代码
• 需要了解错误处理模式
• 需要管理多个会话
• 需要实现交互式助手
• 需要查看自定义 Agent 定义示例

patterns.md — 在以下情况下阅读：

• 需要了解适用于生产环境的架构模式
• 需要集成流式 UI
• 需要了解 MCP 服务集成模式
• 需要了解速率限制和重试模式
• 需要提取结构化输出

drift-detection.md — 在以下情况下阅读：

• 需要了解此技能如何保持最新
• 需要了解验证工作流
• 需要了解更新流程

快速参考

常见事件类型

事件类型（TS/Go）	Python 枚举
assistant.message_delta	SessionEventType.ASSISTANT_MESSAGE_DELTA
session.idle	SessionEventType.SESSION_IDLE
tool.invocation	SessionEventType.TOOL_EXECUTION_START
tool.result	SessionEventType.TOOL_EXECUTION_COMPLETE

Python：导入 from copilot.generated.session_events import SessionEventType

默认工具

默认情况下，SDK 以 --allow-all 模式运行，可使用：

• 文件系统操作
• Git 操作
• Web 请求
• 所有第一方 Copilot 工具

与 Amplihack 集成

使用 Copilot SDK 在 amplihack 中构建自定义 Agent：

# Create Copilot-powered agent for specific domain
from copilot import CopilotClient

async def create_code_review_agent():
    client = CopilotClient()
    await client.start()
    session = await client.create_session({
        "model": "gpt-4.1",
        "streaming": True,
        "systemMessage": {
            "content": "You are an expert code reviewer."
        }
    })
    return session

后续步骤

1. 从简单开始：使用默认模型进行基本的发送和接收
2. 添加流式传输：提供实时响应，改善用户体验
3. 添加工具：为你的领域定制函数
4. 连接 MCP：使用 GitHub MCP 服务访问代码仓库
5. 构建界面：集成到你的应用程序中

如需完整的 API 详情，请参阅 reference.md。 如需查看所有语言的可运行代码，请参阅 examples.md。 如需了解生产环境模式，请参阅 patterns.md。