GitHub Copilot SDK

flowchart TD
  subgraph User["Your Application"]
    App[App code]
  end
  subgraph SDK_LANG["SDK layer - pick one"]
    NODE[nodejs SDK
client.ts, session.ts]
    PY[python SDK
client.py, session.py]
    GO[go SDK
client.go, session.go]
    NET[dotnet SDK
Client.cs, Session.cs]
  end
  subgraph CONTRACT["Shared contract"]
    SCH[api.schema.json
session-events.schema.json]
    VER[sdk-protocol-version.json]
    CODEGEN[scripts codegen
emits rpc + session_events]
    TESTS[test snapshots YAML
conformance fixtures]
  end
  subgraph CLI["Copilot CLI subprocess"]
    AGT[Agent loop
plan -> tool -> respond]
    TOOLS[Builtin tools
shell, file, web]
    MCP[MCP servers
optional sub-processes]
  end

  App -->|language-native API| NODE
  App -->|language-native API| PY
  App -->|language-native API| GO
  App -->|language-native API| NET

  NODE -->|JSON-RPC / stdio or TCP| AGT
  PY -->|JSON-RPC / stdio or TCP| AGT
  GO -->|JSON-RPC / stdio or TCP| AGT
  NET -->|JSON-RPC / stdio or TCP| AGT

  SCH -->|read at build| CODEGEN
  VER -->|embedded constant| NODE
  VER -->|embedded constant| PY
  VER -->|embedded constant| GO
  VER -->|embedded constant| NET
  CODEGEN -->|generated/ rpc.ts| NODE
  CODEGEN -->|generated/ rpc.py| PY
  CODEGEN -->|rpc generated_rpc.go| GO
  CODEGEN -->|Generated/ Rpc.cs| NET

  TESTS -.runs against.-> NODE
  TESTS -.runs against.-> PY
  TESTS -.runs against.-> GO
  TESTS -.runs against.-> NET

  AGT --> TOOLS
  AGT --> MCP

sequenceDiagram
    participant App as Your App
    participant SDK as SDK Client
    participant CLI as Copilot CLI subprocess
    participant LLM as LLM provider

    App->>SDK: new CopilotClient / createSession
    SDK->>CLI: spawn / TCP connect
    SDK->>CLI: JSON-RPC getStatus
    CLI-->>SDK: protocolVersion + capabilities
    Note over SDK,CLI: WHY: negotiate features before first turn
    SDK->>CLI: JSON-RPC session.create
    CLI-->>SDK: sessionId + session.capabilities
    App->>SDK: session.sendAndWait(prompt)
    SDK->>SDK: register idle listener (race fix)
    SDK->>CLI: JSON-RPC session.send
    CLI->>LLM: prompt + tools + system message
    LLM-->>CLI: assistant response
    CLI-->>SDK: event: assistant.message (streamed)
    CLI-->>SDK: event: session.idle
    SDK-->>App: resolved Promise / Task / channel
    App->>SDK: client.stop() / dispose
    SDK->>CLI: JSON-RPC shutdown

sequenceDiagram
    participant LLM as LLM
    participant CLI as Copilot CLI
    participant SDK as SDK (server-to-client RPC)
    participant Hook as preToolUse hook
    participant Perm as Permission handler
    participant Tool as User tool handler

    LLM->>CLI: decide: call get_weather(Seattle)
    CLI->>SDK: session/toolInvoke RPC
    Note over CLI,SDK: WHY: CLI calls back into SDK because tool lives in user code
    SDK->>Hook: pre-tool-use(toolName, args)
    Hook-->>SDK: modified args OR deny
    SDK->>Perm: request approval?
    Note over SDK,Perm: WHY: user gates destructive actions before execution
    Perm-->>SDK: approved
    SDK->>Tool: handler(args)
    Tool-->>SDK: "Cloudy, 62F"
    SDK-->>CLI: RPC reply with result
    CLI->>LLM: tool result appended to context
    LLM-->>CLI: final assistant message
    CLI-->>SDK: event: assistant.message + session.idle

flowchart LR
  SCH[api.schema.json
session-events.schema.json
from @github/copilot/schemas]
  UTILS[scripts/codegen/utils.ts
postProcessSchema]
  TSE[typescript.ts]
  PYE[python.ts]
  GOE[go.ts]
  CSE[csharp.ts]
  NODE[nodejs/src/generated/rpc.ts
nodejs/src/generated/session-events.ts]
  PY[python/copilot/generated/rpc.py
session_events.py]
  GO[go/rpc/generated_rpc.go]
  NET[dotnet/src/Generated/Rpc.cs
SessionEvents.cs]

  SCH --> UTILS
  UTILS --> TSE --> NODE
  UTILS --> PYE --> PY
  UTILS --> GOE --> GO
  UTILS --> CSE --> NET

sequenceDiagram
    participant App as User App
    participant SDK as SDK client-side handlers
    participant RPC as JSON-RPC connection
Content-Length framed
    participant CLI as CLI server-side handlers

    App->>SDK: client.createSession()
    SDK->>RPC: request: session.create {config}
    RPC->>CLI: bytes
    CLI->>CLI: spawn internal session
    CLI-->>RPC: response {sessionId, capabilities}
    Note over RPC: SDK -> CLI: user-intent calls

    App->>SDK: session.send("hello")
    SDK->>RPC: request: session.send
    RPC->>CLI: bytes

    CLI->>RPC: notification: assistant.message
    RPC->>SDK: dispatched to SessionEvent listeners
    SDK-->>App: event callback fires

    CLI->>RPC: request: session/toolInvoke {tool,args}
    Note over RPC: CLI -> SDK: tool/permission/FS calls (bidirectional!)
    RPC->>SDK: dispatched to registered tool handler
    SDK->>App: user's tool code runs
    App-->>SDK: tool result
    SDK->>RPC: response {result}
    RPC->>CLI: bytes

    CLI->>RPC: notification: session.idle
    RPC->>SDK: resolves sendAndWait promise