build-copilot-sdk-app（构建 GitHub Copilot SDK 应用）

Build Copilot SDK App

Build applications powered by GitHub Copilot using the @github/copilot-sdk TypeScript/Node.js package (protocol v3). The SDK communicates with the Copilot CLI over JSON-RPC (stdio or TCP) and exposes a session-based API for sending prompts, receiving streamed responses, registering custom tools, handling permissions, and managing agent workflows.

Decision tree

What do you need?
│
├── New app from scratch
│   ├── Install & basic example ──────────► Quick start (below) — npm init, ESM setup, first prompt
│   ├── Client options & transport ───────► references/client-and-transport.md — stdio vs TCP, CopilotClient config
│   └── Authentication ──────────────────► references/auth-and-byok.md — OAuth, tokens, BYOK with 5 providers
│
├── Sessions
│   ├── Create / resume / disconnect ────► references/sessions.md — lifecycle, create-or-resume pattern
│   ├── Infinite sessions & compaction ──► references/sessions.md — long conversations, context window mgmt
│   └── Persistence & resumption ────────► references/sessions.md — disk persistence, resumeSession semantics
│
├── Messages & streaming
│   ├── send / sendAndWait ──────────────► Quick start (below) — blocking vs fire-and-forget
│   ├── Streaming deltas ────────────────► references/events-and-streaming.md — incremental content delivery
│   └── All 47 event types ─────────────► references/events-and-streaming.md — full event catalog
│
├── Custom tools
│   ├── defineTool with Zod ─────────────► references/tools-and-schemas.md — Zod schema, handler, auto-JSON-Schema
│   ├── JSON Schema tools ──────────────► references/tools-and-schemas.md — raw schema without Zod
│   └── Override built-in tools ────────► references/tools-and-schemas.md — replace default Copilot tools
│
├── Permissions & user input
│   ├── Permission handler ─────────────► references/permissions-and-user-input.md — approveAll or custom logic
│   ├── ask_user / onUserInputRequest ──► references/permissions-and-user-input.md — programmatic user prompts
│   └── Elicitation (MCP forms) ────────► references/permissions-and-user-input.md — structured input via MCP
│
├── Hooks (lifecycle interceptors)
│   ├── Pre/post tool use ──────────────► references/hooks.md — intercept tool calls, modify args/results
│   ├── Prompt modification ────────────► references/hooks.md — rewrite prompts before send
│   └── Session lifecycle & errors ─────► references/hooks.md — onError, onSessionStart, void return OK
│
├── Agents, MCP & skills
│   ├── Custom agents ──────────────────► references/agents-mcp-skills.md — agent registration & routing
│   ├── MCP server config ─────────────► references/agents-mcp-skills.md — connect external MCP servers
│   ├── Skills system ─────────────────► references/agents-mcp-skills.md — skill discovery & invocation
│   └── CLI extensions (.mjs) ─────────► references/agents-mcp-skills.md — extend Copilot CLI via scripts
│
├── Advanced patterns
│   ├── Plan / autopilot / interactive ─► references/advanced-patterns.md — mode switching workflow
│   ├── Fleet mode ─────────────────────► references/advanced-patterns.md — parallel session orchestration
│   ├── Multi-client architecture ──────► references/advanced-patterns.md — multiple CopilotClient instances
│   ├── Ralph loop (autonomous dev) ───► references/advanced-patterns.md — autonomous code generation loop
│   ├── Steering & queueing ───────────► references/advanced-patterns.md — prompt queueing, backpressure
│   └── System message modes ──────────► references/advanced-patterns.md — system prompt configuration
│
├── Auth & BYOK
│   ├── GitHub OAuth / tokens ──────────► references/auth-and-byok.md — token acquisition flow
│   └── Bring Your Own Key ────────────► references/auth-and-byok.md — OpenAI/Anthropic/Azure/Gemini/Ollama
│
└── Type reference
    └── All interfaces & RPC methods ──► references/types-reference.md — TypeScript interfaces, RPC API

Quick start

Prerequisites

Verify your environment:

node --version   # must be >= 20
copilot --version # Copilot CLI must be installed

Authenticate before you run the examples:

• Local interactive auth: copilot login
• Headless auth: set one of COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN
• In CI or other non-interactive runs, export the token before npm start; do not expect the SDK process to complete browser login for you.

Default file layout and run command

Use this layout unless the repo already has a better convention:

mkdir -p src/lib
npm pkg set scripts.start="tsx src/index.ts"
npm pkg set scripts.dev="tsx watch src/index.ts"

• Put the main SDK entrypoint in src/index.ts
• Put reusable local business logic in src/lib/*.ts
• Run the first build with npm start

Project setup

npm init -y
npm pkg set type=module   # SDK is ESM-only
npm install @github/copilot-sdk tsx zod

ESM required. The SDK only ships ESM exports. Your package.json must have "type": "module".

Common imports

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

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

// Advanced — hooks, resume, types
import type { SessionConfig, ToolInvocation } from "@github/copilot-sdk";

Minimal example

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

const client = new CopilotClient();
const auth = await client.getAuthStatus();

if (!auth.isAuthenticated) {
  throw new Error(
    "Authenticate with `copilot login` or set COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN first."
  );
}

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

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

await session.disconnect();
await client.stop();

Save this as src/index.ts, then run npm start.

If startup does not progress:

• Check auth.isAuthenticated first and stop there if it is false
• In headless environments, set COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN before launching Node
• Re-run with new CopilotClient({logLevel: "debug"}) and follow references/auth-and-byok.md for auth preflight

With streaming

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

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

session.on("session.idle", async () => {
  console.log("\n--- done ---");
  await session.disconnect();
  await client.stop();
});

await session.send({ prompt: "Explain TypeScript generics" });

With a custom tool

Create the imported helper first:

// src/lib/math.ts
export function add(a: number, b: number) {
  return a + b;
}

import { CopilotClient, defineTool, approveAll } from "@github/copilot-sdk";
import { z } from "zod";
import { add } from "./lib/math.ts";

const addNumbers = defineTool("add_numbers", {
  description: "Add two numbers using local business logic",
  parameters: z.object({
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  }),
  handler: async ({ a, b }) => ({ result: add(a, b) }),
});

const client = new CopilotClient();
const session = await client.createSession({
  model: "gpt-4.1",
  tools: [addNumbers],
  onPermissionRequest: approveAll,
});

const response = await session.sendAndWait({
  prompt: "Use the add_numbers tool to add 19 and 23.",
});
console.log(response?.data.content);

await session.disconnect();
await client.stop();

Default convention: keep imported domain helpers under src/lib/ and wire them into tool handlers instead of hard-coding toy data inside the handler. If the real logic lives in another package, import a workspace dependency or package entrypoint that tsx can resolve at runtime instead of a source-only deep path.

Key patterns

Send-and-wait vs fire-and-forget

// Blocking — waits for session.idle, returns last assistant.message
const response = await session.sendAndWait(
  { prompt: "Hello" },
  30_000, // optional timeout in ms
);

// Non-blocking — returns immediately, events arrive via session.on()
await session.send({ prompt: "Start a long task..." });

Event subscription (typed + wildcard)

// Typed — only fires for the specific event type
const unsub = session.on("tool.execution_complete", (event) => {
  console.log(`${event.data.toolName}: ${event.data.success}`);
});

// Wildcard — fires for every event
session.on((event) => {
  if (event.type === "session.error") {
    console.error(event.data.message);
  }
});

unsub(); // unsubscribe

Session persistence

// Create with a stable ID
const session = await client.createSession({
  sessionId: "user-123-conversation",
  model: "gpt-4.1",
  onPermissionRequest: approveAll,
});
await session.sendAndWait({ prompt: "Let's discuss TypeScript" });
await session.disconnect(); // preserves state on disk

// Resume later (same or different client)
const resumed = await client.resumeSession("user-123-conversation", {
  onPermissionRequest: approveAll,
});

Create-or-resume pattern

createSession always starts fresh — only resumeSession restores conversation context. In applications that may revisit a session:

let session;
try {
  session = await client.resumeSession(sessionId, {
    onPermissionRequest: approveAll,
  });
} catch {
  session = await client.createSession({
    sessionId,
    model: "gpt-4.1",
    onPermissionRequest: approveAll,
  });
}

Handling ask_user programmatically

const session = await client.createSession({
  onPermissionRequest: approveAll,
  onUserInputRequest: async (request) => {
    if (request.choices?.length) {
      return { answer: request.choices[0], wasFreeform: false };
    }
    return { answer: "Yes, proceed", wasFreeform: true };
  },
});

Plan / autopilot mode

await session.rpc.mode.set({ mode: "plan" });

session.on("exit_plan_mode.requested", (event) => {
  console.log("Plan ready:", event.data.summary);
  session.rpc.mode.set({ mode: "autopilot" });
});

Abort in-flight work

await session.send({ prompt: "Run sleep 100" });
await session.abort(); // cancels current work; session remains usable

Common pitfalls

Steering notes for AI agents

These notes are distilled from real-world testing. They address the exact points where an agent following these instructions literally will get stuck.

Project initialization

• Always run npm init -y then npm pkg set type=module before installing. The SDK is ESM-only and will throw ERR_PACKAGE_PATH_NOT_EXPORTED without this.
• Always install zod alongside the SDK if you plan to use defineTool. It's not bundled.
• Verify node --version is >= 20 and copilot --version responds before writing any code.

Session lifecycle

• createSession always starts fresh — even with the same sessionId. It does NOT restore previous messages.
• To resume a conversation, use resumeSession(sessionId). If the session doesn't exist, it throws — catch and fall back to createSession.
• Always call session.disconnect() then client.stop() when done. Without this, streaming processes hang indefinitely because the RPC connection keeps the event loop alive.

Streaming

• Register all event handlers (session.on(...)) before calling session.send(). Handlers registered after send may miss early events.
• In the session.idle handler, always include cleanup (disconnect + stop) unless you're building a multi-turn REPL.
• When the model calls multiple tools in parallel, tool.execution_start and tool.execution_complete events interleave. Use toolCallId to correlate them.

Tools

• defineTool requires a Zod schema for parameters. The SDK auto-detects Zod and calls toJSONSchema().
• Tool handler errors are caught and surfaced to the model as error results — they don't crash your process.
• Tool names must be globally unique across all extensions.

Timeouts and errors

• sendAndWait timeout does not abort in-flight work. It only stops waiting. Call session.abort() explicitly if you need to cancel.
• BYOK without model in provider config creates a session successfully but fails silently at send time. Always pair provider with model.