diff --git a/README.md b/README.md
index 2f6e0d26..f106d3da 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,7 @@ Discover our curated collections of prompts, instructions, and agents organized
| Name | Description | Items | Tags |
| ---- | ----------- | ----- | ---- |
| [Awesome Copilot](collections/awesome-copilot.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, collections, instructions, prompts, and skills. | 5 items | github-copilot, discovery, meta, prompt-engineering, agents |
-| [Copilot SDK](collections/copilot-sdk.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 4 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot |
+| [Copilot SDK](collections/copilot-sdk.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 5 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot |
| [Partners](collections/partners.md) | Custom agents that have been created by GitHub partners | 20 items | devops, security, database, cloud, infrastructure, observability, feature-flags, cicd, migration, performance |
diff --git a/collections/copilot-sdk.collection.yml b/collections/copilot-sdk.collection.yml
index 1f1b534a..c5688331 100644
--- a/collections/copilot-sdk.collection.yml
+++ b/collections/copilot-sdk.collection.yml
@@ -11,6 +11,8 @@ items:
kind: instruction
- path: instructions/copilot-sdk-python.instructions.md
kind: instruction
+ - path: skills/copilot-sdk/SKILL.md
+ kind: skill
display:
ordering: manual
show_badge: true
diff --git a/collections/copilot-sdk.md b/collections/copilot-sdk.md
index c5fa1fac..26c96991 100644
--- a/collections/copilot-sdk.md
+++ b/collections/copilot-sdk.md
@@ -12,6 +12,7 @@ Build applications with the GitHub Copilot SDK across multiple programming langu
| [GitHub Copilot SDK Go Instructions](../instructions/copilot-sdk-go.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-sdk-go.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-sdk-go.instructions.md) | Instruction | This file provides guidance on building Go applications using GitHub Copilot SDK. |
| [GitHub Copilot SDK Node.js Instructions](../instructions/copilot-sdk-nodejs.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-sdk-nodejs.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-sdk-nodejs.instructions.md) | Instruction | This file provides guidance on building Node.js/TypeScript applications using GitHub Copilot SDK. |
| [GitHub Copilot SDK Python Instructions](../instructions/copilot-sdk-python.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-sdk-python.instructions.md)
[](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fcopilot-sdk-python.instructions.md) | Instruction | This file provides guidance on building Python applications using GitHub Copilot SDK. |
+| [Copilot Sdk](../skills/copilot-sdk/SKILL.md) | Skill | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. |
---
-*This collection includes 4 curated items for **Copilot SDK**.*
\ No newline at end of file
+*This collection includes 5 curated items for **Copilot SDK**.*
\ No newline at end of file
diff --git a/docs/README.collections.md b/docs/README.collections.md
index a1eba0df..99d59107 100644
--- a/docs/README.collections.md
+++ b/docs/README.collections.md
@@ -17,7 +17,7 @@ Curated collections of related prompts, instructions, and agents organized aroun
| Name | Description | Items | Tags |
| ---- | ----------- | ----- | ---- |
| [⭐ Awesome Copilot](../collections/awesome-copilot.md) | Meta prompts that help you discover and generate curated GitHub Copilot agents, collections, instructions, prompts, and skills. | 5 items | github-copilot, discovery, meta, prompt-engineering, agents |
-| [⭐ Copilot SDK](../collections/copilot-sdk.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 4 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot |
+| [⭐ Copilot SDK](../collections/copilot-sdk.md) | Build applications with the GitHub Copilot SDK across multiple programming languages. Includes comprehensive instructions for C#, Go, Node.js/TypeScript, and Python to help you create AI-powered applications. | 5 items | copilot-sdk, sdk, csharp, go, nodejs, typescript, python, ai, github-copilot |
| [⭐ Partners](../collections/partners.md) | Custom agents that have been created by GitHub partners | 20 items | devops, security, database, cloud, infrastructure, observability, feature-flags, cicd, migration, performance |
| [Azure & Cloud Development](../collections/azure-cloud-development.md) | Comprehensive Azure cloud development tools including Infrastructure as Code, serverless functions, architecture patterns, and cost optimization for building scalable cloud applications. | 18 items | azure, cloud, infrastructure, bicep, terraform, serverless, architecture, devops |
| [C# .NET Development](../collections/csharp-dotnet-development.md) | Essential prompts, instructions, and chat modes for C# and .NET development including testing, documentation, and best practices. | 8 items | csharp, dotnet, aspnet, testing |
diff --git a/docs/README.skills.md b/docs/README.skills.md
index 26d252de..45a9d055 100644
--- a/docs/README.skills.md
+++ b/docs/README.skills.md
@@ -30,6 +30,7 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
| [azure-role-selector](../skills/azure-role-selector/SKILL.md) | When user is asking for guidance for which role to assign to an identity given desired permissions, this agent helps them understand the role that will meet the requirements with least privilege access and how to apply that role. | `LICENSE.txt` |
| [azure-static-web-apps](../skills/azure-static-web-apps/SKILL.md) | Helps create, configure, and deploy Azure Static Web Apps using the SWA CLI. Use when deploying static sites to Azure, setting up SWA local development, configuring staticwebapp.config.json, adding Azure Functions APIs to SWA, or setting up GitHub Actions CI/CD for Static Web Apps. | None |
| [chrome-devtools](../skills/chrome-devtools/SKILL.md) | Expert-level browser automation, debugging, and performance analysis using Chrome DevTools MCP. Use for interacting with web pages, capturing screenshots, analyzing network traffic, and profiling performance. | None |
+| [copilot-sdk](../skills/copilot-sdk/SKILL.md) | Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent. | None |
| [gh-cli](../skills/gh-cli/SKILL.md) | GitHub CLI (gh) comprehensive reference for repositories, issues, pull requests, Actions, projects, releases, gists, codespaces, organizations, extensions, and all GitHub operations from the command line. | None |
| [git-commit](../skills/git-commit/SKILL.md) | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None |
| [github-issues](../skills/github-issues/SKILL.md) | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, or manage issue workflows. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", or any GitHub issue management task. | `references/templates.md` |
diff --git a/eng/validate-collections.mjs b/eng/validate-collections.mjs
index cb95657f..e85c1b87 100644
--- a/eng/validate-collections.mjs
+++ b/eng/validate-collections.mjs
@@ -2,12 +2,12 @@
import fs from "fs";
import path from "path";
-import { parseCollectionYaml, parseFrontmatter } from "./yaml-parser.mjs";
import {
- ROOT_FOLDER,
COLLECTIONS_DIR,
MAX_COLLECTION_ITEMS,
+ ROOT_FOLDER,
} from "./constants.mjs";
+import { parseCollectionYaml, parseFrontmatter } from "./yaml-parser.mjs";
// Validation functions
function validateCollectionId(id) {
@@ -177,10 +177,10 @@ function validateCollectionItems(items) {
if (!item.kind || typeof item.kind !== "string") {
return `Item ${i + 1} must have a kind string`;
}
- if (!["prompt", "instruction", "agent"].includes(item.kind)) {
+ if (!["prompt", "instruction", "agent", "skill"].includes(item.kind)) {
return `Item ${
i + 1
- } kind must be one of: prompt, instruction, agent`;
+ } kind must be one of: prompt, instruction, agent, skill`;
}
// Validate file path exists
@@ -365,4 +365,3 @@ try {
console.error(`Error during validation: ${error.message}`);
process.exit(1);
}
-
diff --git a/skills/copilot-sdk/SKILL.md b/skills/copilot-sdk/SKILL.md
new file mode 100644
index 00000000..ea18108e
--- /dev/null
+++ b/skills/copilot-sdk/SKILL.md
@@ -0,0 +1,863 @@
+---
+name: copilot-sdk
+description: Build agentic applications with GitHub Copilot SDK. Use when embedding AI agents in apps, creating custom tools, implementing streaming responses, managing sessions, connecting to MCP servers, or creating custom agents. Triggers on Copilot SDK, GitHub SDK, agentic app, embed Copilot, programmable agent, MCP server, custom agent.
+---
+
+# GitHub Copilot SDK
+
+Embed Copilot's agentic workflows in any application using Python, TypeScript, Go, or .NET.
+
+## Overview
+
+The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-tested agent runtime you can invoke programmatically. No need to build your own orchestration - you define agent behavior, Copilot handles planning, tool invocation, file edits, and more.
+
+## Prerequisites
+
+1. **GitHub Copilot CLI** installed and authenticated ([Installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli))
+2. **Language runtime**: Node.js 18+, Python 3.8+, Go 1.21+, or .NET 8.0+
+
+Verify CLI: `copilot --version`
+
+## Installation
+
+### Node.js/TypeScript
+```bash
+mkdir copilot-demo && cd copilot-demo
+npm init -y --init-type module
+npm install @github/copilot-sdk tsx
+```
+
+### Python
+```bash
+pip install github-copilot-sdk
+```
+
+### Go
+```bash
+mkdir copilot-demo && cd copilot-demo
+go mod init copilot-demo
+go get github.com/github/copilot-sdk/go
+```
+
+### .NET
+```bash
+dotnet new console -n CopilotDemo && cd CopilotDemo
+dotnet add package GitHub.Copilot.SDK
+```
+
+## Quick Start
+
+### 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();
+process.exit(0);
+```
+
+Run: `npx tsx index.ts`
+
+### 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())
+```
+
+### Go
+```go
+package main
+
+import (
+ "fmt"
+ "log"
+ "os"
+ copilot "github.com/github/copilot-sdk/go"
+)
+
+func main() {
+ client := copilot.NewClient(nil)
+ if err := client.Start(); err != nil {
+ log.Fatal(err)
+ }
+ defer client.Stop()
+
+ session, err := client.CreateSession(&copilot.SessionConfig{Model: "gpt-4.1"})
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ response, err := session.SendAndWait(copilot.MessageOptions{Prompt: "What is 2 + 2?"}, 0)
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ fmt.Println(*response.Data.Content)
+ os.Exit(0)
+}
+```
+
+### .NET (C#)
+```csharp
+using GitHub.Copilot.SDK;
+
+await using var client = new CopilotClient();
+await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
+
+var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
+Console.WriteLine(response?.Data.Content);
+```
+
+Run: `dotnet run`
+
+## Streaming Responses
+
+Enable real-time output for better UX:
+
+### TypeScript
+```typescript
+import { CopilotClient, SessionEvent } from "@github/copilot-sdk";
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ streaming: true,
+});
+
+session.on((event: SessionEvent) => {
+ if (event.type === "assistant.message_delta") {
+ process.stdout.write(event.data.deltaContent);
+ }
+ if (event.type === "session.idle") {
+ console.log(); // New line when done
+ }
+});
+
+await session.sendAndWait({ prompt: "Tell me a short joke" });
+
+await client.stop();
+process.exit(0);
+```
+
+### Python
+```python
+import asyncio
+import sys
+from copilot import CopilotClient
+from copilot.generated.session_events import SessionEventType
+
+async def main():
+ client = CopilotClient()
+ await client.start()
+
+ session = await client.create_session({
+ "model": "gpt-4.1",
+ "streaming": True,
+ })
+
+ def handle_event(event):
+ if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
+ sys.stdout.write(event.data.delta_content)
+ sys.stdout.flush()
+ if event.type == SessionEventType.SESSION_IDLE:
+ print()
+
+ session.on(handle_event)
+ await session.send_and_wait({"prompt": "Tell me a short joke"})
+ await client.stop()
+
+asyncio.run(main())
+```
+
+### Go
+```go
+session, err := client.CreateSession(&copilot.SessionConfig{
+ Model: "gpt-4.1",
+ Streaming: true,
+})
+
+session.On(func(event copilot.SessionEvent) {
+ if event.Type == "assistant.message_delta" {
+ fmt.Print(*event.Data.DeltaContent)
+ }
+ if event.Type == "session.idle" {
+ fmt.Println()
+ }
+})
+
+_, err = session.SendAndWait(copilot.MessageOptions{Prompt: "Tell me a short joke"}, 0)
+```
+
+### .NET
+```csharp
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-4.1",
+ Streaming = true,
+});
+
+session.On(ev =>
+{
+ if (ev is AssistantMessageDeltaEvent deltaEvent)
+ Console.Write(deltaEvent.Data.DeltaContent);
+ if (ev is SessionIdleEvent)
+ Console.WriteLine();
+});
+
+await session.SendAndWaitAsync(new MessageOptions { Prompt = "Tell me a short joke" });
+```
+
+## Custom Tools
+
+Define tools that Copilot can invoke during reasoning. When you define a tool, you tell Copilot:
+1. **What the tool does** (description)
+2. **What parameters it needs** (schema)
+3. **What code to run** (handler)
+
+### TypeScript (JSON Schema)
+```typescript
+import { CopilotClient, defineTool, SessionEvent } 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, call a weather API here
+ const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
+ const temp = Math.floor(Math.random() * 30) + 50;
+ const condition = conditions[Math.floor(Math.random() * conditions.length)];
+ return { city, temperature: `${temp}°F`, condition };
+ },
+});
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ streaming: true,
+ tools: [getWeather],
+});
+
+session.on((event: SessionEvent) => {
+ if (event.type === "assistant.message_delta") {
+ process.stdout.write(event.data.deltaContent);
+ }
+});
+
+await session.sendAndWait({
+ prompt: "What's the weather like in Seattle and Tokyo?",
+});
+
+await client.stop();
+process.exit(0);
+```
+
+### Python (Pydantic)
+```python
+import asyncio
+import random
+import sys
+from copilot import CopilotClient
+from copilot.tools import define_tool
+from copilot.generated.session_events import SessionEventType
+from pydantic import BaseModel, Field
+
+class GetWeatherParams(BaseModel):
+ city: str = Field(description="The name of the city to get weather for")
+
+@define_tool(description="Get the current weather for a city")
+async def get_weather(params: GetWeatherParams) -> dict:
+ city = params.city
+ conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]
+ temp = random.randint(50, 80)
+ condition = random.choice(conditions)
+ return {"city": city, "temperature": f"{temp}°F", "condition": condition}
+
+async def main():
+ client = CopilotClient()
+ await client.start()
+
+ session = await client.create_session({
+ "model": "gpt-4.1",
+ "streaming": True,
+ "tools": [get_weather],
+ })
+
+ def handle_event(event):
+ if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
+ sys.stdout.write(event.data.delta_content)
+ sys.stdout.flush()
+
+ session.on(handle_event)
+
+ await session.send_and_wait({
+ "prompt": "What's the weather like in Seattle and Tokyo?"
+ })
+
+ await client.stop()
+
+asyncio.run(main())
+```
+
+### Go
+```go
+type WeatherParams struct {
+ City string `json:"city" jsonschema:"The city name"`
+}
+
+type WeatherResult struct {
+ City string `json:"city"`
+ Temperature string `json:"temperature"`
+ Condition string `json:"condition"`
+}
+
+getWeather := copilot.DefineTool(
+ "get_weather",
+ "Get the current weather for a city",
+ func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
+ conditions := []string{"sunny", "cloudy", "rainy", "partly cloudy"}
+ temp := rand.Intn(30) + 50
+ condition := conditions[rand.Intn(len(conditions))]
+ return WeatherResult{
+ City: params.City,
+ Temperature: fmt.Sprintf("%d°F", temp),
+ Condition: condition,
+ }, nil
+ },
+)
+
+session, _ := client.CreateSession(&copilot.SessionConfig{
+ Model: "gpt-4.1",
+ Streaming: true,
+ Tools: []copilot.Tool{getWeather},
+})
+```
+
+### .NET (Microsoft.Extensions.AI)
+```csharp
+using GitHub.Copilot.SDK;
+using Microsoft.Extensions.AI;
+using System.ComponentModel;
+
+var getWeather = AIFunctionFactory.Create(
+ ([Description("The city name")] string city) =>
+ {
+ var conditions = new[] { "sunny", "cloudy", "rainy", "partly cloudy" };
+ var temp = Random.Shared.Next(50, 80);
+ var condition = conditions[Random.Shared.Next(conditions.Length)];
+ return new { city, temperature = $"{temp}°F", condition };
+ },
+ "get_weather",
+ "Get the current weather for a city"
+);
+
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-4.1",
+ Streaming = true,
+ Tools = [getWeather],
+});
+```
+
+## How Tools Work
+
+When Copilot decides to call your tool:
+1. Copilot sends a tool call request with the parameters
+2. The SDK runs your handler function
+3. The result is sent back to Copilot
+4. Copilot incorporates the result into its response
+
+Copilot decides when to call your tool based on the user's question and your tool's description.
+
+## Interactive CLI Assistant
+
+Build a complete interactive assistant:
+
+### TypeScript
+```typescript
+import { CopilotClient, defineTool, SessionEvent } from "@github/copilot-sdk";
+import * as readline from "readline";
+
+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 ({ city }) => {
+ const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
+ const temp = Math.floor(Math.random() * 30) + 50;
+ const condition = conditions[Math.floor(Math.random() * conditions.length)];
+ return { city, temperature: `${temp}°F`, condition };
+ },
+});
+
+const client = new CopilotClient();
+const session = await client.createSession({
+ model: "gpt-4.1",
+ streaming: true,
+ tools: [getWeather],
+});
+
+session.on((event: SessionEvent) => {
+ if (event.type === "assistant.message_delta") {
+ process.stdout.write(event.data.deltaContent);
+ }
+});
+
+const rl = readline.createInterface({
+ input: process.stdin,
+ output: process.stdout,
+});
+
+console.log("Weather Assistant (type 'exit' to quit)");
+console.log("Try: 'What's the weather in Paris?'\n");
+
+const prompt = () => {
+ rl.question("You: ", async (input) => {
+ if (input.toLowerCase() === "exit") {
+ await client.stop();
+ rl.close();
+ return;
+ }
+
+ process.stdout.write("Assistant: ");
+ await session.sendAndWait({ prompt: input });
+ console.log("\n");
+ prompt();
+ });
+};
+
+prompt();
+```
+
+### Python
+```python
+import asyncio
+import random
+import sys
+from copilot import CopilotClient
+from copilot.tools import define_tool
+from copilot.generated.session_events import SessionEventType
+from pydantic import BaseModel, Field
+
+class GetWeatherParams(BaseModel):
+ city: str = Field(description="The name of the city to get weather for")
+
+@define_tool(description="Get the current weather for a city")
+async def get_weather(params: GetWeatherParams) -> dict:
+ conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]
+ temp = random.randint(50, 80)
+ condition = random.choice(conditions)
+ return {"city": params.city, "temperature": f"{temp}°F", "condition": condition}
+
+async def main():
+ client = CopilotClient()
+ await client.start()
+
+ session = await client.create_session({
+ "model": "gpt-4.1",
+ "streaming": True,
+ "tools": [get_weather],
+ })
+
+ def handle_event(event):
+ if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
+ sys.stdout.write(event.data.delta_content)
+ sys.stdout.flush()
+
+ session.on(handle_event)
+
+ print("Weather Assistant (type 'exit' to quit)")
+ print("Try: 'What's the weather in Paris?'\n")
+
+ while True:
+ try:
+ user_input = input("You: ")
+ except EOFError:
+ break
+
+ if user_input.lower() == "exit":
+ break
+
+ sys.stdout.write("Assistant: ")
+ await session.send_and_wait({"prompt": user_input})
+ print("\n")
+
+ await client.stop()
+
+asyncio.run(main())
+```
+
+## MCP Server Integration
+
+Connect to MCP (Model Context Protocol) servers for pre-built tools. Connect to GitHub's MCP server for repository, issue, and PR access:
+
+### TypeScript
+```typescript
+const session = await client.createSession({
+ model: "gpt-4.1",
+ mcpServers: {
+ github: {
+ type: "http",
+ url: "https://api.githubcopilot.com/mcp/",
+ },
+ },
+});
+```
+
+### Python
+```python
+session = await client.create_session({
+ "model": "gpt-4.1",
+ "mcp_servers": {
+ "github": {
+ "type": "http",
+ "url": "https://api.githubcopilot.com/mcp/",
+ },
+ },
+})
+```
+
+### Go
+```go
+session, _ := client.CreateSession(&copilot.SessionConfig{
+ Model: "gpt-4.1",
+ MCPServers: map[string]copilot.MCPServerConfig{
+ "github": {
+ Type: "http",
+ URL: "https://api.githubcopilot.com/mcp/",
+ },
+ },
+})
+```
+
+### .NET
+```csharp
+await using var session = await client.CreateSessionAsync(new SessionConfig
+{
+ Model = "gpt-4.1",
+ McpServers = new Dictionary
+ {
+ ["github"] = new McpServerConfig
+ {
+ Type = "http",
+ Url = "https://api.githubcopilot.com/mcp/",
+ },
+ },
+});
+```
+
+## Custom Agents
+
+Define specialized AI personas for specific tasks:
+
+### TypeScript
+```typescript
+const session = await client.createSession({
+ model: "gpt-4.1",
+ 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.",
+ }],
+});
+```
+
+### Python
+```python
+session = await client.create_session({
+ "model": "gpt-4.1",
+ "custom_agents": [{
+ "name": "pr-reviewer",
+ "display_name": "PR Reviewer",
+ "description": "Reviews pull requests for best practices",
+ "prompt": "You are an expert code reviewer. Focus on security, performance, and maintainability.",
+ }],
+})
+```
+
+## System Message
+
+Customize the AI's behavior and personality:
+
+### TypeScript
+```typescript
+const session = await client.createSession({
+ model: "gpt-4.1",
+ systemMessage: {
+ content: "You are a helpful assistant for our engineering team. Always be concise.",
+ },
+});
+```
+
+### Python
+```python
+session = await client.create_session({
+ "model": "gpt-4.1",
+ "system_message": {
+ "content": "You are a helpful assistant for our engineering team. Always be concise.",
+ },
+})
+```
+
+## External CLI Server
+
+Run the CLI in server mode separately and connect the SDK to it. Useful for debugging, resource sharing, or custom environments.
+
+### Start CLI in Server Mode
+```bash
+copilot --server --port 4321
+```
+
+### Connect SDK to External Server
+
+#### TypeScript
+```typescript
+const client = new CopilotClient({
+ cliUrl: "localhost:4321"
+});
+
+const session = await client.createSession({ model: "gpt-4.1" });
+```
+
+#### Python
+```python
+client = CopilotClient({
+ "cli_url": "localhost:4321"
+})
+await client.start()
+
+session = await client.create_session({"model": "gpt-4.1"})
+```
+
+#### Go
+```go
+client := copilot.NewClient(&copilot.ClientOptions{
+ CLIUrl: "localhost:4321",
+})
+
+if err := client.Start(); err != nil {
+ log.Fatal(err)
+}
+
+session, _ := client.CreateSession(&copilot.SessionConfig{Model: "gpt-4.1"})
+```
+
+#### .NET
+```csharp
+using var client = new CopilotClient(new CopilotClientOptions
+{
+ CliUrl = "localhost:4321"
+});
+
+await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
+```
+
+**Note:** When `cliUrl` is provided, the SDK will not spawn or manage a CLI process - it only connects to the existing server.
+
+## Event Types
+
+| Event | Description |
+|-------|-------------|
+| `user.message` | User input added |
+| `assistant.message` | Complete model response |
+| `assistant.message_delta` | Streaming response chunk |
+| `assistant.reasoning` | Model reasoning (model-dependent) |
+| `assistant.reasoning_delta` | Streaming reasoning chunk |
+| `tool.execution_start` | Tool invocation started |
+| `tool.execution_complete` | Tool execution finished |
+| `session.idle` | No active processing |
+| `session.error` | Error occurred |
+
+## Client Configuration
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `cliPath` | Path to Copilot CLI executable | System PATH |
+| `cliUrl` | Connect to existing server (e.g., "localhost:4321") | None |
+| `port` | Server communication port | Random |
+| `useStdio` | Use stdio transport instead of TCP | true |
+| `logLevel` | Logging verbosity | "info" |
+| `autoStart` | Launch server automatically | true |
+| `autoRestart` | Restart on crashes | true |
+| `cwd` | Working directory for CLI process | Inherited |
+
+## Session Configuration
+
+| Option | Description |
+|--------|-------------|
+| `model` | LLM to use ("gpt-4.1", "claude-sonnet-4.5", etc.) |
+| `sessionId` | Custom session identifier |
+| `tools` | Custom tool definitions |
+| `mcpServers` | MCP server connections |
+| `customAgents` | Custom agent personas |
+| `systemMessage` | Override default system prompt |
+| `streaming` | Enable incremental response chunks |
+| `availableTools` | Whitelist of permitted tools |
+| `excludedTools` | Blacklist of disabled tools |
+
+## Session Persistence
+
+Save and resume conversations across restarts:
+
+### Create with Custom ID
+```typescript
+const session = await client.createSession({
+ sessionId: "user-123-conversation",
+ model: "gpt-4.1"
+});
+```
+
+### Resume Session
+```typescript
+const session = await client.resumeSession("user-123-conversation");
+await session.send({ prompt: "What did we discuss earlier?" });
+```
+
+### List and Delete Sessions
+```typescript
+const sessions = await client.listSessions();
+await client.deleteSession("old-session-id");
+```
+
+## Error Handling
+
+```typescript
+try {
+ const client = new CopilotClient();
+ const session = await client.createSession({ model: "gpt-4.1" });
+ const response = await session.sendAndWait(
+ { prompt: "Hello!" },
+ 30000 // timeout in ms
+ );
+} catch (error) {
+ if (error.code === "ENOENT") {
+ console.error("Copilot CLI not installed");
+ } else if (error.code === "ECONNREFUSED") {
+ console.error("Cannot connect to Copilot server");
+ } else {
+ console.error("Error:", error.message);
+ }
+} finally {
+ await client.stop();
+}
+```
+
+## Graceful Shutdown
+
+```typescript
+process.on("SIGINT", async () => {
+ console.log("Shutting down...");
+ await client.stop();
+ process.exit(0);
+});
+```
+
+## Common Patterns
+
+### Multi-turn Conversation
+```typescript
+const session = await client.createSession({ model: "gpt-4.1" });
+
+await session.sendAndWait({ prompt: "My name is Alice" });
+await session.sendAndWait({ prompt: "What's my name?" });
+// Response: "Your name is Alice"
+```
+
+### File Attachments
+```typescript
+await session.send({
+ prompt: "Analyze this file",
+ attachments: [{
+ type: "file",
+ path: "./data.csv",
+ displayName: "Sales Data"
+ }]
+});
+```
+
+### Abort Long Operations
+```typescript
+const timeoutId = setTimeout(() => {
+ session.abort();
+}, 60000);
+
+session.on((event) => {
+ if (event.type === "session.idle") {
+ clearTimeout(timeoutId);
+ }
+});
+```
+
+## Available Models
+
+Query available models at runtime:
+
+```typescript
+const models = await client.getModels();
+// Returns: ["gpt-4.1", "gpt-4o", "claude-sonnet-4.5", ...]
+```
+
+## Best Practices
+
+1. **Always cleanup**: Use `try-finally` or `defer` to ensure `client.stop()` is called
+2. **Set timeouts**: Use `sendAndWait` with timeout for long operations
+3. **Handle events**: Subscribe to error events for robust error handling
+4. **Use streaming**: Enable streaming for better UX on long responses
+5. **Persist sessions**: Use custom session IDs for multi-turn conversations
+6. **Define clear tools**: Write descriptive tool names and descriptions
+
+## Architecture
+
+```
+Your Application
+ |
+ SDK Client
+ | JSON-RPC
+ Copilot CLI (server mode)
+ |
+ GitHub (models, auth)
+```
+
+The SDK manages the CLI process lifecycle automatically. All communication happens via JSON-RPC over stdio or TCP.
+
+## Resources
+
+- **GitHub Repository**: https://github.com/github/copilot-sdk
+- **Getting Started Tutorial**: https://github.com/github/copilot-sdk/blob/main/docs/tutorials/first-app.md
+- **GitHub MCP Server**: https://github.com/github/github-mcp-server
+- **MCP Servers Directory**: https://github.com/modelcontextprotocol/servers
+- **Cookbook**: https://github.com/github/copilot-sdk/tree/main/cookbook
+- **Samples**: https://github.com/github/copilot-sdk/tree/main/samples
+
+## Status
+
+This SDK is in **Technical Preview** and may have breaking changes. Not recommended for production use yet.