copilot-sdk-dotnet

# GitHub Copilot CLI SDK (.NET) Use this skill to guide SDK integration, select appropriate APIs, and provide C# code examples. Focus on practical implementation patterns for .NET. ## Quick workflow 1. Identify the user's goal (client creation, session management, streaming, custom tools, permissions, MCP integration, or custom agents). 2. Determine if the user needs basic `CopilotClient` or `Microsoft.Agents.AI` integration. 3. Select the matching API section and code pattern. 4. Provide C# examples with clear context (usings, initialization, event handling). 5. Call out important defaults and configuration options that affect behavior. 6. Clarify stability scope: Agent Framework is RC (stable API surface toward GA) while Copilot SDK pieces may still evolve. ## SDK selection and installation ### Core SDK (Direct Integration) - **.NET**: `dotnet add package GitHub.Copilot.SDK` (uses AIFunctionFactory and attributes) ### Microsoft Agent Framework (Wrapper) - **.NET**: `dotnet add package Microsoft.Agents.AI.GitHub.Copilot --prerelease` Note: - Microsoft Agent Framework is in Release Candidate and has a stable API surface for 1.0 planning. - Keep prerelease suffixes where package feeds still require them, and pin versions in implementation docs. All SDKs communicate via JSON-RPC over stdio (default) or TCP transports. ## Core concepts - **CopilotClient**: Main entry point managing server lifecycle, connections, and session creation. Can spawn CLI server automatically or connect to external server. - **Sessions**: Represent individual conversations with persistent state, event handlers, and tool registrations. Each session has a sessionId, model, and optional streaming/tools configuration. - **Tools**: Custom functions the assistant can invoke. Support type-safe schemas via `AIFunctionFactory` or manual definitions. - **MCP Servers**: External tool servers (local stdio, HTTP, or SSE) extending assistant capabilities. - **Custom Agents**: Specialized personas with scoped prompts, tool access, and configurations. - **Streaming**: Real-time response delivery via event handlers (e.g., `assistant.message_delta` for chunks). ## Microsoft Agent Framework Integration For .NET, use the Microsoft Agent Framework wrapper to treat Copilot as a building block in larger agentic systems. - **Consistent Abstraction**: Implements `AIAgent`. - **Multi-Agent Workflows**: Compose Copilot agents with Azure OpenAI/Anthropic agents. - **Features**: Supports streaming, function tools, sessions, and MCP servers via framework patterns. - **RC Guidance**: Favor Agent Framework abstractions (`AIAgent`, workflows, approvals) for new orchestration code instead of building direct orchestration plumbing on top of raw session events. ## Migration Guidance (SK/AutoGen -> Agent Framework) When users are migrating existing agent systems: 1. Inventory existing Semantic Kernel or AutoGen flows (single-agent, tool calls, orchestration, HITL). 2. Map to Agent Framework primitives first (`AIAgent`, tools, workflows, checkpoints, approvals). 3. Reuse Copilot SDK at integration boundaries (session/tool transport), not as the primary orchestration model. 4. Validate parity for streaming output, approval gates, and failure recovery before full cutover. **See [Agent Framework Integration](references/agent-framework.md) for full guide on installation, agent creation, and multi-agent orchestration.** ## Client creation patterns ### Default client (auto-spawns CLI server) - **.NET**: `await using var client = new CopilotClient();` ### Client with options Common options: - `CliPath`: Custom CLI binary path (default: auto-detect) - `LogLevel`: "none", "error", "warning", "info", "debug", "all" - `AutoStart`: Auto-spawn server on first use (default: true) - `AutoRestart`: Auto-restart on crash (default: true) - `UseStdio`: Use stdio transport (default: true) - `Port`: TCP port (0 = random, only when useStdio is false) - `Cwd`: Working directory for CLI process ### External server connection Use `CliUrl` to connect to existing server: - `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"` ### Lifecycle management - `await client.StartAsync()` (manual start if AutoStart is false) - `client.State` (returns "disconnected", "connecting", "connected", "error") - `await client.PingAsync()` (verify connectivity) - `await client.StopAsync()` (graceful shutdown) - `await client.ForceStopAsync()` (force stop if graceful shutdown hangs) ## Session creation and management ### Basic session ```csharp var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" }); ``` ### Session with full configuration Common options: - `SessionId`: Custom session identifier (optional) - `Model`: Model to use (e.g., "gpt-5", "claude-sonnet-4.5") - `Streaming`: Enable streaming responses (default: false) - `AvailableTools`: Whitelist specific tools - `ExcludedTools`: Blacklist specific tools - `SystemMessage`: Custom system prompt with mode ("append" or "replace") - `OnPermissionRequest`: Permission handler function > **Reasoning effort (known gap)**: The SDK `SessionConfig` surface does not currently document a reasoning-effort option, while the CLI (`--reasoning-effort`) and VS Code (`supportsReasoningEffort`) expose it. If your workload needs per-model reasoning-effort control and the SDK version does not expose it, prefer the CLI path (`copilot-cli-subsession`) or VS Code BYOK. See the [parity matrix](../copilot-cli-subsession/references/copilot-sdk-parity-matrix.md) and the [feature audit](../copilot-cli-subsession/references/copilot-cli-feature-verification-audit.md). ### Session queries - `await client.ListSessionsAsync()` (all sessions) - `await client.GetLastSessionIdAsync()` (for resuming) - `await client.ResumeSessionAsync(sessionId, options)` (re-open existing) - `await client.DeleteSessionAsync(sessionId)` (permanent delete) - `await session.DestroyAsync()` (release resources, don't delete) ## Message handling and events ### Event subscription pattern Subscribe before sending messages. Use `session.Events` (IObservable or event based): ```csharp session.Events.Subscribe(@event => { switch (@event) { case UserMessageEvent: // User's input case AssistantMessageEvent: // Complete response case AssistantMessageDeltaEvent: // Streaming chunk case ToolExecutionStartEvent: // Tool invoked case ToolExecutionEndEvent: // Tool completed case SessionIdleEvent: // No activity case SessionErrorEvent: // Error occurred } }); ``` ### Send patterns **Synchronous (wait for completion)**: ```csharp var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "Your question", Attachments = [/* optional files/dirs */] }, TimeSpan.FromSeconds(60)); // Optional timeout ``` **Asynchronous (non-blocking, event-driven)**: ```csharp var messageId = await session.SendAsync(new MessageOptions { Prompt = "Long task", Mode = MessageMode.Enqueue // or Immediate }); ``` ### File attachments Support two types: ```csharp Attachments = [ new Attachment { Type = "file", Path = "/path/to/file", DisplayName = "File" }, new Attachment { Type = "directory", Path = "/path/to/dir", DisplayName = "Folder" } ] ``` ### Conversation history ```csharp var history = await session.GetMessagesAsync(); ``` ### Abort long-running requests ```csharp await session.AbortAsync(); ``` ## Custom tools (type-safe) ### .NET (AIFunctionFactory) ```csharp using Microsoft.Extensions.AI; using System.ComponentModel; var myTool = AIFunctionFactory.Create( async ([Description("...")] string param1) => { // Implementation return new { result = "..." }; }, "tool_name", "What this tool does" ); var session = await client.CreateSessionAsync(new SessionConfig { Tools = new[] { myTool } }); ``` ### Tool result structure (raw schema pattern) All languages support returning rich structured results: ```json { "textResultForLlm": "Human-readable text for model", "resultType": "success", // or "failure" "sessionLog": "Internal diagnostic message", "toolTelemetry": { /* structured data */ }, "error": "Error message if failure" } ``` ## Permission handling Register a permission handler to approve/deny sensitive operations. Available kinds: "shell", "write", "read", "url", "mcp". ### .NET pattern ```csharp var session = await client.CreateSessionAsync(new SessionConfig { OnPermissionRequest = async (request, context) => { switch (request.Kind) { case "write": var path = request.Properties["path"]?.ToString(); if (path?.StartsWith("/safe/") == true) { return new PermissionRequestResult { Kind = "approved" }; } return new PermissionRequestResult { Kind = "denied-by-rules", Message = "Path not allowed" }; case "shell": return new PermissionRequestResult { Kind = "denied-interactively-by-user" }; case "read": return new PermissionRequestResult { Kind = "approved" }; default: return new PermissionRequestResult { Kind = "denied-no-approval-rule-and-could-not-request-from-user" }; } } }); ``` ### Result kinds - `"approved"`: Allow the operation - `"denied-by-rules"`: Deny with rule explanation - `"denied-interactively-by-user"`: User denied - `"denied-no-approval-rule-and-could-not-request-from-user"`: No rule and no user interaction ## Custom provider configuration (BYOK) Use your own API keys with OpenAI, Azure OpenAI, Anthropic, or compatible providers. ### .NET pattern ```csharp var session = await client.CreateSessionAsync(new SessionConfig { Provider = new ProviderConfig { Type = "azure", BaseUrl = "https://your-resource.openai.azure.com", ApiKey = Environment.GetEnvironmentVariable("AZURE_OPENAI_KEY"), Azure = new AzureProviderConfig { ApiVersion = "2024-10-21" } } }); ``` ## MCP Server integration Connect local (stdio) or remote (HTTP/SSE) MCP servers. ### .NET pattern ```csharp using GitHub.Copilot.SDK.Mcp; var session = await client.CreateSessionAsync(new SessionConfig { McpServers = new Dictionary<string, McpServerConfig> { ["filesystem"] = new McpLocalServerConfig { Type = "local", Command = "npx", Args = ["-y", "@modelcontextprotocol/server-filesystem", "/path"], Tools = "*" }, ["remote-api"] = new McpRemoteServerConfig { Type = "http", Url = "https://mcp-server.example.com/mcp", Tools = ["search"] } } }); ``` ## Custom agents Define specialized personas with scoped system prompts and tool access. ### .NET pattern ```csharp var session = await client.CreateSessionAsync(new SessionConfig { CustomAgents = [ new CustomAgent { Name = "security-reviewer", DisplayName = "Security Reviewer", Description = "Reviews code for vulnerabilities", Prompt = "You are a security expert...", Tools = ["Read", "Grep", "Glob"], Infer = true } ] }); // Invoke via prompt await session.SendAndWaitAsync(new MessageOptions { Prompt = "@security-reviewer Review src/auth.cs" }); ``` ## Common patterns and best practices ### Pattern 1: Simple request-response ```csharp await using var client = new CopilotClient(); await client.StartAsync(); await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" }); var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "Your question" }); Console.WriteLine(response.Data.Content); ``` ### Pattern 2: Streaming with events ```csharp var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5", Streaming = true }); session.Events.Subscribe(@event => { if (@event is AssistantMessageDeltaEvent delta) { Console.Write(delta.DeltaContent); } }); await session.SendAndWaitAsync(new MessageOptions { Prompt = "Write a story" }); ``` ### Pattern 3: Tool invocation with events ```csharp var session = await client.CreateSessionAsync(new SessionConfig { Tools = new[] { myTool } }); session.Events.Subscribe(@event => { if (@event is ToolExecutionStartEvent start) { Console.WriteLine($"Tool {start.ToolName} started"); } }); await session.SendAndWaitAsync(new MessageOptions { Prompt = "Use the tool" }); ``` ### Pattern 4: File attachments ```csharp await session.SendAndWaitAsync(new MessageOptions { Prompt = "Analyze this code", Attachments = [ new Attachment { Type = "file", Path = "./src/Program.cs", DisplayName = "Main" } ] }); ``` ### Pattern 5: Multi-language BYOK setup Choose the provider once during session creation. ## Glossary of GitHub Copilot Products The GitHub Copilot ecosystem comprises multiple distinct products, each serving different use cases and contexts. Understanding the boundaries between them is essential for choosing the right tool and understanding SDK capabilities. | Product | Alias | Description | Execution Context | Primary Interface | Key Use Cases |