From 9c5aa1bf2e0c4931680954ee64b5c400fadb680f Mon Sep 17 00:00:00 2001 From: Will Date: Sat, 28 Feb 2026 18:02:32 +0000 Subject: [PATCH] docs: update Copilot SDK skill that reorganize language-specific guides for .NET, Go, Python, and TypeScript --- docs/README.skills.md | 2 +- skills/copilot-sdk/SKILL.md | 778 +------------------- skills/copilot-sdk/references/dotnet.md | 129 ++++ skills/copilot-sdk/references/go.md | 156 ++++ skills/copilot-sdk/references/python.md | 250 +++++++ skills/copilot-sdk/references/typescript.md | 346 +++++++++ 6 files changed, 893 insertions(+), 768 deletions(-) create mode 100644 skills/copilot-sdk/references/dotnet.md create mode 100644 skills/copilot-sdk/references/go.md create mode 100644 skills/copilot-sdk/references/python.md create mode 100644 skills/copilot-sdk/references/typescript.md diff --git a/docs/README.skills.md b/docs/README.skills.md index e3c5e5fd8..c9afa4d4b 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -62,7 +62,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [convert-plaintext-to-md](../skills/convert-plaintext-to-md/SKILL.md) | Convert a text-based document to markdown following instructions from prompt, or if a documented option is passed, follow the instructions for that option. | None | | [copilot-cli-quickstart](../skills/copilot-cli-quickstart/SKILL.md) | Use this skill when someone wants to learn GitHub Copilot CLI from scratch. Offers interactive step-by-step tutorials with separate Developer and Non-Developer tracks, plus on-demand Q&A. Just say "start tutorial" or ask a question! Note: This skill targets GitHub Copilot CLI specifically and uses CLI-specific tools (ask_user, sql, fetch_copilot_cli_documentation). | None | | [copilot-instructions-blueprint-generator](../skills/copilot-instructions-blueprint-generator/SKILL.md) | Technology-agnostic blueprint generator for creating comprehensive copilot-instructions.md files that guide GitHub Copilot to produce code consistent with project standards, architecture patterns, and exact technology versions by analyzing existing codebase patterns and avoiding assumptions. | 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 | +| [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. | `references/dotnet.md`
`references/go.md`
`references/python.md`
`references/typescript.md` | | [copilot-usage-metrics](../skills/copilot-usage-metrics/SKILL.md) | Retrieve and display GitHub Copilot usage metrics for organizations and enterprises using the GitHub CLI and REST API. | `get-enterprise-metrics.sh`
`get-enterprise-user-metrics.sh`
`get-org-metrics.sh`
`get-org-user-metrics.sh` | | [cosmosdb-datamodeling](../skills/cosmosdb-datamodeling/SKILL.md) | Step-by-step guide for capturing key application requirements for NoSQL use-case and produce Azure Cosmos DB Data NoSQL Model design using best practices and common patterns, artifacts_produced: "cosmosdb_requirements.md" file and "cosmosdb_data_model.md" file | None | | [create-agentsmd](../skills/create-agentsmd/SKILL.md) | Prompt for generating an AGENTS.md file for a repository | None | diff --git a/skills/copilot-sdk/SKILL.md b/skills/copilot-sdk/SKILL.md index ea18108eb..3ca5c0270 100644 --- a/skills/copilot-sdk/SKILL.md +++ b/skills/copilot-sdk/SKILL.md @@ -7,6 +7,8 @@ description: Build agentic applications with GitHub Copilot SDK. Use when embedd Embed Copilot's agentic workflows in any application using Python, TypeScript, Go, or .NET. +Use this file as the high-level architecture and workflow guide. Keep language-specific implementation details in `references/`. + ## 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. @@ -18,671 +20,6 @@ The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production- 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 | @@ -724,107 +61,15 @@ await using var session = await client.CreateSessionAsync(new SessionConfig { Mo | `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 +## How Tools Work -Query available models at runtime: +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 -```typescript -const models = await client.getModels(); -// Returns: ["gpt-4.1", "gpt-4o", "claude-sonnet-4.5", ...] -``` +Copilot decides when to call your tool based on the user's question and your tool's description. ## Best Practices @@ -852,11 +97,10 @@ The SDK manages the CLI process lifecycle automatically. All communication happe ## 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 +- **Getting Started Guide**: https://github.com/github/copilot-sdk/blob/main/docs/getting-started.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 +- **Cookbook**: https://github.com/github/awesome-copilot/tree/main/cookbook ## Status diff --git a/skills/copilot-sdk/references/dotnet.md b/skills/copilot-sdk/references/dotnet.md new file mode 100644 index 000000000..0edfc2a99 --- /dev/null +++ b/skills/copilot-sdk/references/dotnet.md @@ -0,0 +1,129 @@ +# .NET Guide + +Use this reference when the user explicitly asks for .NET / C#. + +## Prerequisites + +- .NET 8.0+ +- GitHub Copilot CLI installed and authenticated (`copilot --version`) + +## Install + +```bash +dotnet new console -n CopilotDemo && cd CopilotDemo +dotnet add package GitHub.Copilot.SDK +``` + +## Quick Start + +```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: + +```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 (Microsoft.Extensions.AI) + +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) + +```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], +}); +``` + +## 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: + +```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/", + }, + }, +}); +``` + +## 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 + +```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. + +## Samples + +- .NET: https://github.com/github/copilot-sdk/tree/main/dotnet/samples diff --git a/skills/copilot-sdk/references/go.md b/skills/copilot-sdk/references/go.md new file mode 100644 index 000000000..a1979d973 --- /dev/null +++ b/skills/copilot-sdk/references/go.md @@ -0,0 +1,156 @@ +# Go Guide + +Use this reference when the user explicitly asks for Go. + +## Prerequisites + +- Go 1.21+ +- GitHub Copilot CLI installed and authenticated (`copilot --version`) + +## Install + +```bash +mkdir copilot-demo && cd copilot-demo +go mod init copilot-demo +go get github.com/github/copilot-sdk/go +``` + +## Quick Start + +```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) +} +``` + +## Streaming Responses + +Enable real-time output for better UX: + +```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) +``` + +## 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) + +```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}, +}) +``` + +## 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: + +```go +session, _ := client.CreateSession(&copilot.SessionConfig{ + Model: "gpt-4.1", + MCPServers: map[string]copilot.MCPServerConfig{ + "github": { + Type: "http", + URL: "https://api.githubcopilot.com/mcp/", + }, + }, +}) +``` + +## 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 + +```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"}) +``` + +## Samples + +- Go: https://github.com/github/copilot-sdk/tree/main/go/samples diff --git a/skills/copilot-sdk/references/python.md b/skills/copilot-sdk/references/python.md new file mode 100644 index 000000000..4d3af4f27 --- /dev/null +++ b/skills/copilot-sdk/references/python.md @@ -0,0 +1,250 @@ +# Python Guide + +Use this reference when the user explicitly asks for Python. + +## Prerequisites + +- Python 3.8+ +- GitHub Copilot CLI installed and authenticated (`copilot --version`) + +## Install + +```bash +pip install github-copilot-sdk +``` + +## Quick Start + +```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()) +``` + +## Streaming Responses + +Enable real-time output for better UX: + +```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()) +``` + +## Custom Tools (Pydantic) + +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) + +```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()) +``` + +## Interactive CLI Assistant + +Build a complete interactive assistant: + +```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: + +```python +session = await client.create_session({ + "model": "gpt-4.1", + "mcp_servers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + }, + }, +}) +``` + +## Custom Agents + +Define specialized AI personas for specific tasks: + +```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: + +```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 + +```python +client = CopilotClient({ + "cli_url": "localhost:4321" +}) +await client.start() + +session = await client.create_session({"model": "gpt-4.1"}) +``` + +## Samples + +- Python: https://github.com/github/copilot-sdk/tree/main/python/samples diff --git a/skills/copilot-sdk/references/typescript.md b/skills/copilot-sdk/references/typescript.md new file mode 100644 index 000000000..476b48135 --- /dev/null +++ b/skills/copilot-sdk/references/typescript.md @@ -0,0 +1,346 @@ +# TypeScript / Node.js Guide + +Use this reference when the user explicitly asks for TypeScript or Node.js. + +## Prerequisites + +- Node.js 18+ +- GitHub Copilot CLI installed and authenticated (`copilot --version`) + +## Install + +```bash +mkdir copilot-demo && cd copilot-demo +npm init -y --init-type module +npm install @github/copilot-sdk tsx +``` + +## Quick Start + +```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` + +## Streaming Responses + +Enable real-time output for better UX: + +```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); +``` + +## 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 +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); +``` + +## Interactive CLI Assistant + +Build a complete interactive assistant: + +```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(); +``` + +## 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 +const session = await client.createSession({ + model: "gpt-4.1", + mcpServers: { + github: { + type: "http", + url: "https://api.githubcopilot.com/mcp/", + }, + }, +}); +``` + +## Custom Agents + +Define specialized AI personas for specific tasks: + +```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.", + }], +}); +``` + +## System Message + +Customize the AI's behavior and personality: + +```typescript +const session = await client.createSession({ + model: "gpt-4.1", + systemMessage: { + 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 +const client = new CopilotClient({ + cliUrl: "localhost:4321" +}); + +const session = await client.createSession({ model: "gpt-4.1" }); +``` + +## 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 +const client = new CopilotClient(); +try { + 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", ...] +``` + +## Samples + +- Node.js: https://github.com/github/copilot-sdk/tree/main/nodejs/samples