copilot-sdk-dotnet

name	copilot-sdk-dotnet
description	Build applications with GitHub Copilot CLI SDKs for .NET. Use for direct CopilotClient integration or Microsoft Agent Framework. Covers sessions, streaming, tools, MCP, permissions, and multi-agent workflows.
metadata	{"version":"1.2.0","authors":"arisng","lastVerified":"2026-08-03T00:00:00.000Z"}

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 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

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 and the feature audit.

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):

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):

var response = await session.SendAndWaitAsync(new MessageOptions {
    Prompt = "Your question",
    Attachments = [/* optional files/dirs */]
}, TimeSpan.FromSeconds(60)); // Optional timeout

Asynchronous (non-blocking, event-driven):

var messageId = await session.SendAsync(new MessageOptions {
    Prompt = "Long task",
    Mode = MessageMode.Enqueue // or Immediate
});

File attachments

Support two types:

Attachments = [
    new Attachment { Type = "file", Path = "/path/to/file", DisplayName = "File" },
    new Attachment { Type = "directory", Path = "/path/to/dir", DisplayName = "Folder" }
]

Conversation history

var history = await session.GetMessagesAsync();

Abort long-running requests

await session.AbortAsync();

Custom tools (type-safe)

.NET (AIFunctionFactory)

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:

{
    "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

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

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

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

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

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

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

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

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 |