This skill provides guidance for creating agents and applications with the GitHub Copilot SDK. It should be used when the user wants to create, modify, or work on software that uses the GitHub Copilot SDK in TypeScript, Python, Go, or .NET. The skill covers SDK usage patterns, CLI configuration, custom tools, MCP servers, and custom agents.
npxskills add intellectronica/agent-skills--skill copilot-sdkLoading…
The GitHub Copilot SDK exposes the same Copilot CLI agent runtime over JSON-RPC, so apps can drive Copilot programmatically instead of building their own orchestration layer.
Status: Public preview
SDKs: Node.js/TypeScript, Python, Go, .NET, Java
Architecture: Application -> SDK client -> JSON-RPC -> Copilot CLI
When helping with the Copilot SDK:
docs/ as the source of truth for shared behavior.listModels() is available.go tool bundler workflow.github/copilot-sdk-java and expects the CLI to be installed separately.DefaultAzureCredential.approveAllPermissionHandler.approve_allcopilot.PermissionHandler.ApproveAllPermissionHandler.ApproveAllPermissionHandler.APPROVE_ALLdisconnect()destroy()sessionId when creating them.cliUrl.copilot --headless --port 4321
client.listModels() and the official supported-models page.reasoningEffort exists for models that support it.| SDK | Install |
|---|---|
| Node.js / TypeScript | npm install @github/copilot-sdk |
| Python | pip install github-copilot-sdk |
| Go | go get github.com/github/copilot-sdk/go |
| .NET | dotnet add package GitHub.Copilot.SDK |
| Java | Maven/Gradle package com.github:copilot-sdk-java |
Pick the setup that matches the application shape:
cliUrl.Use the same mental model in every language:
send() if you need streaming or progress.send() or sendAndWait().session.idle or the returned final message.disconnect() the session and stop/dispose the client.import { CopilotClient, approveAll } from "@github/copilot-sdk";
const client = new CopilotClient();
await client.start();
const session = await client.createSession({
model: "gpt-5",
streaming: true,
onPermissionRequest: approveAll,
});
session.on("assistant.message_delta", (event) => {
process.stdout.write(event.data.deltaContent ?? "");
});
await session.sendAndWait({ prompt: "What is 2+2?" });
await session.disconnect();
await client.stop();
Common operations across SDKs:
start(), stop(), forceStop()createSession(), resumeSession(), disconnect()send(), sendAndWait(), abort(), getMessages()listModels(), listSessions(), / assistant.message.assistant.message_delta.session.idle is the reliable "turn complete" signal.See references/event-system.md.
defineTool(...) with Zod or raw JSON Schema.@define_tool with Pydantic models.DefineTool(...).AIFunctionFactory.Create(...).overridesBuiltInTool: trueoverrides_built_in_tool=TrueOverridesBuiltInTool = trueAdditionalProperties["is_override"] = trueskipPermission.customAgents lets you define sub-agents per session.mcpServers attaches local or remote MCP servers.onPreToolUse, onPostToolUse, onUserPromptSubmitted, and lifecycle/error hooks.skillDirectories; disable selectively with disabledSkills.See references/cli-agents-mcp.md.
mode: "immediate" for steering and mode: "enqueue" for queueing.commands.onUserInputRequest.session.ui when the connected client supports them.TelemetryConfig.onGetTraceContext callback for outbound propagation.sessionId for resumable sessions.infiniteSessions for long-running workflows that may need compaction.~/.copilot/session-state/ unless configuration overrides it.| Concept | TypeScript | Python | Go | .NET | Java |
|---|---|---|---|---|---|
| Create session | createSession() | create_session() | CreateSession() | CreateSessionAsync() | createSession() |
| Resume session | resumeSession() | resume_session() |
destroy() still appears in older examples but disconnect() is the current method.assistant.message and assistant.message_delta use event.data.*, not top-level event.content.send().sessionId is awkward to operationalize.references/working-examples.md - current starter examples, including tools and resume patternsreferences/event-system.md - event names, lifecycle, and language access patternsreferences/cli-agents-mcp.md - custom agents, skills, MCP, headless CLI, and config locationsreferences/troubleshooting.md - common failures, debug logging, auth, permissions, and transport issuesgetStatus()ping()ResumeSession() |
ResumeSessionAsync() |
resumeSession() |
| Final content | event.data.content | event.data.content | *event.Data.Content | evt.Data.Content | event.getData().content() |
| Delta content | event.data.deltaContent | event.data.delta_content | *event.Data.DeltaContent | evt.Data.DeltaContent | event.getData().deltaContent() |
| Skills field | skillDirectories | skill_directories | SkillDirectories | SkillDirectories | setSkillDirectories(...) |
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).