github-copilot-sdk

# GitHub Copilot SDK - Comprehensive Skill

## Overview

The **GitHub Copilot SDK** enables developers to embed Copilot's agentic workflows programmatically in their applications. It exposes the same engine behind Copilot CLI as a production-tested agent runtime you can invoke from code.

### When to Use the Copilot SDK

**Use the Copilot SDK when:**

- Building applications that need Copilot's AI capabilities
- Implementing custom AI assistants with tool-calling abilities
- Creating integrations that leverage Copilot's code understanding
- Connecting to MCP (Model Context Protocol) servers for standardized tools
- Need streaming responses in custom UIs

**Don't use when:**

- GitHub Copilot CLI is sufficient (use CLI directly)
- No programmatic integration needed (use Copilot in VS Code)
- Building simple chat without tools (use standard LLM API)

### Language Support

| SDK                    | Installation                              |
| ---------------------- | ----------------------------------------- |
| **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`   |

### Prerequisites

1. **GitHub Copilot CLI installed** and authenticated
2. **Active Copilot subscription** (free tier available with limits)

## Quick Start

### Minimal Example (TypeScript)

```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();
```

### Minimal Example (Python)

```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())
```

### Add Streaming

```typescript
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" });
```

### Add Custom Tool

```typescript
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],
});
```

## Core Concepts

### Architecture

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

The SDK manages the CLI process lifecycle automatically or connects to an external CLI server.

### Key Components

1. **CopilotClient**: Entry point - manages connection to Copilot CLI
2. **Session**: Conversation context with model, tools, and history
3. **Tools**: Custom functions Copilot can invoke
4. **Events**: Streaming responses and tool call notifications
5. **MCP Integration**: Connect to Model Context Protocol servers

### Session Configuration

```typescript
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.",
    },
  ],
});
```

## Navigation Guide

### When to Read Supporting Files

**reference.md** - Read when you need:

- Complete API reference for all 4 languages
- All method signatures with parameters and return types
- Session configuration options
- Event types and handling
- External CLI server connection

**examples.md** - Read when you need:

- Working copy-paste code for all 4 languages
- Error handling patterns
- Multiple sessions management
- Interactive assistant implementation
- Custom agent definition examples

**patterns.md** - Read when you need:

- Production-ready architectural patterns
- Streaming UI integration
- MCP server integration patterns
- Rate limiting and retry patterns
- Structured output extraction

**drift-detection.md** - Read when you need:

- Understanding how this skill stays current
- Validation workflow
- Update procedures

## Quick Reference

### Common Event Types

| Event Type (TS/Go)        | Python Enum                                |
| ------------------------- | ------------------------------------------ |
| `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**: Import `from copilot.generated.session_events import SessionEventType`

### Default Tools

The SDK operates in `--allow-all` mode by default, enabling:

- File system operations
- Git operations
- Web requests
- All first-party Copilot tools

## Integration with Amplihack

Use the Copilot SDK to build custom agents within amplihack:

```python
# 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
```

## Next Steps

1. **Start Simple**: Basic send/receive with default model
2. **Add Streaming**: Real-time responses for better UX
3. **Add Tools**: Custom functions for your domain
4. **Connect MCP**: Use GitHub MCP server for repo access
5. **Build UI**: Integrate into your application

For complete API details, see `reference.md`.
For working code in all languages, see `examples.md`.
For production patterns, see `patterns.md`.